---
url: https://kernelsu.org/zh_CN/guide/module-config.md
---
# 模块配置

KernelSU 提供了一个内置的配置系统,允许模块存储持久化或临时的键值设置。配置以二进制格式存储在 `/data/adb/ksu/module_configs/<module_id>/`,具有以下特性:

## 配置类型

* **持久配置** (`persist.config`):重启后保留,直到明确删除或卸载模块
* **临时配置** (`tmp.config`):在每次启动时的 post-fs-data 阶段自动清除

读取配置时,对于同一个键,临时值优先于持久值。

## 在模块脚本中使用配置

所有模块脚本(`post-fs-data.sh`、`service.sh`、`boot-completed.sh` 等)运行时都会设置 `KSU_MODULE` 环境变量为模块 ID。您可以使用 `ksud module config` 命令来管理模块的配置:

```bash
# 获取配置值
value=$(ksud module config get my_setting)

# 设置持久配置值
ksud module config set my_setting "some value"

# 设置临时配置值(重启后清除)
ksud module config set --temp runtime_state "active"

# 从 stdin 设置值(适用于多行或复杂数据)
ksud module config set my_key <<EOF
多行
文本值
EOF

# 或从命令管道输入
echo "value" | ksud module config set my_key

# 显式使用 stdin 标志
cat file.json | ksud module config set json_data --stdin

# 列出所有配置项(合并持久和临时配置)
ksud module config list

# 删除配置项
ksud module config delete my_setting

# 删除临时配置项
ksud module config delete --temp runtime_state

# 清除所有持久配置
ksud module config clear

# 清除所有临时配置
ksud module config clear --temp
```

## 验证限制

配置系统强制执行以下限制:

* **最大键长度**:256 字节
* **最大值长度**:1MB (1048576 字节)
* **最大配置项数**:每个模块 32 个
* **键格式**:必须匹配 `^[a-zA-Z][a-zA-Z0-9._-]+$`(与模块 ID 相同)
  * 必须以字母(a-zA-Z)开头
  * 可包含字母、数字、点(`.`)、下划线(`_`)或连字符(`-`)
  * 最小长度:2 个字符
* **值格式**:无限制 - 可包含任何 UTF-8 字符,包括换行符、控制字符等
  * 以二进制格式存储,带长度前缀,确保安全处理所有数据

## 生命周期

* **启动时**:所有临时配置在 post-fs-data 阶段清除
* **模块卸载时**:所有配置(持久和临时)自动删除
* 配置以二进制格式存储,使用魔数 `0x4b53554d`("KSUM")和版本验证

## 使用场景

配置系统适用于:

* **用户偏好**:存储用户通过 WebUI 或 action 脚本配置的模块设置
* **功能开关**:在不重新安装的情况下启用/禁用模块功能
* **运行时状态**:跟踪应在重启时重置的临时状态(使用临时配置)
* **安装设置**:记住模块安装时做出的选择
* **复杂数据**:存储 JSON、多行文本、Base64 编码数据或任何结构化内容(最多 1MB)

::: tip 最佳实践

* 对于应在重启后保留的用户偏好,使用持久配置
* 对于应在启动时重置的运行时状态或功能开关,使用临时配置
* 在脚本中使用配置值之前验证它们
* 使用 `ksud module config list` 命令调试配置问题
  :::

## 高级功能

模块配置系统提供了用于高级用例的特殊配置键:

### 覆盖模块描述 {#overriding-module-description}

您可以通过设置 `override.description` 配置键来动态覆盖 `module.prop` 中的 `description` 字段:

```bash
# 覆盖模块描述
ksud module config set override.description "在管理器中显示的自定义描述"
```

当获取模块列表时,如果存在 `override.description` 配置,它将替换 `module.prop` 中的原始描述。这对于以下场景很有用:

* 在模块描述中显示动态状态信息
* 向用户显示运行时配置详情
* 基于模块状态更新描述而无需重新安装

### 声明管理的功能

模块可以使用 `manage.<feature>` 配置模式声明它们管理的 KernelSU 功能。支持的功能对应于 KernelSU 内部的 `FeatureId` 枚举:

**支持的功能:**

* `su_compat` - SU 兼容模式
* `kernel_umount` - 内核自动卸载

```bash
# 声明此模块管理 SU 兼容性并将其启用
ksud module config set manage.su_compat true

# 声明此模块管理内核卸载并将其禁用
ksud module config set manage.kernel_umount false

# 移除功能管理(模块不再控制此功能)
ksud module config delete manage.su_compat
```

**工作原理:**

* `manage.<feature>` 键的存在表示模块正在管理该功能
* 值表示期望的状态:`true`/`1` 代表启用,`false`/`0`(或任何其他值)代表禁用
* 要停止管理某个功能,请完全删除该配置键

管理的功能通过模块列表 API 以 `managedFeatures` 字段(逗号分隔的字符串)公开。这允许:

* KernelSU 管理器检测哪些模块管理哪些 KernelSU 功能
* 防止多个模块尝试管理同一功能时发生冲突
* 更好地协调模块与核心 KernelSU 功能之间的关系

::: warning 仅支持预定义功能
仅使用上面列出的预定义功能名称(`su_compat`、`kernel_umount`)。这些对应于实际的 KernelSU 内部功能。使用其他功能名称不会导致错误,但没有任何功能作用。
:::