命令行 > 环境变量 > 配置文件 > 默认值:Usage 配置解析优先级完全指南
命令行 > 环境变量 > 配置文件 > 默认值:Usage 配置解析优先级完全指南
用 Usage 定义 CLI 时,同一个配置项可能同时出现在命令行参数、环境变量、配置文件和默认值里,到底听谁的?这份完整指南讲清 Usage 配置解析优先级的 5 层规则、合并策略、作用域限制,以及用一条命令追踪"值到底从哪来"的实用技巧。
一、5 层优先级:顺序固定,不可协商
Usage 的配置解析(configuration resolution)把值来源分成若干层(layer):命令行、环境变量、配置文件、其他来源(如 git config),每一层提供"配置项 + 值"的条目。合并时按固定顺序从高层往低层取:
| 优先级 | 层 | 典型例子 |
|---|---|---|
| 1 | 命令行 | --jobs 8 |
| 2 | 环境变量 | EX_JOBS=6 |
| 3 | 配置文件(离用户越近越优先) | 当前目录 hk.toml 优先于 ~/.config/hk.toml |
| 4 | CLI 自行声明的其他来源 | git config hk.jobs |
| 5 | 声明的默认值 | default = 4 |
规则核心就一句话:高层没给值,就不动低层的值——"提供不了值"不等于"清除值"。官方定义见 docs/spec/resolution.md,配套的测试向量在 corpus/config/01-precedence.kdl。
一个经典例子:
vector "cli-beats-env-beats-file" doc="The declared order decides: the command line, then the environment, then a file." {
setting "jobs" type="uint" default=4
layer "cli" id="--jobs" { value "jobs" "8" }
layer "env" id="EX_JOBS" { value "jobs" "6" }
layer "file" id="hk.toml" { value "jobs" "2" }
expect { value "jobs" 8 origin "jobs" "--jobs" }
}
命令行写了 8、环境变量写了 6、文件写了 2,最终结果是 8,且记录来源为 --jobs。
二、配置文件之间谁赢?离你越近越赢
同一层内部也有顺序:最近的文件优先。当前目录的 hk.toml 会覆盖 ~/.config/hk.toml,后者又覆盖系统级配置。这个顺序在 spec 里通过 file 声明书写顺序表达(最后声明的优先级最高):
config {
file "/etc/mycli/config.toml" scope="system"
file "~/.config/mycli/config.toml" scope="global"
file "mycli.toml" findup=#true
}
带 .local 后缀的变体优先于其基础文件,所以 mycli.local.toml 能覆盖 mycli.toml。完整字段说明在 docs/spec/reference/config.md。
三、合并策略:replace、union、deep
多个层对同一个集合类配置项"都有话说"时怎么办?由配置项自己声明一次合并策略,而不是每层各说了算:
| 策略 | 行为 | 适用场景 |
|---|---|---|
replace(默认) |
最高层直接获胜 | 标量值,几乎总是它 |
union |
各层的条目全部累加,低层在前 | 项目排除项要"加上"而不是"盖掉"机器级的排除项 |
deep |
按 key 逐键合并,高层赢共享键 | map / 嵌套配置 |
两个容易忽略的细节:
- 默认值是最底层,不是"没人设置时才填上"。
union列表配了默认值再叠加文件值,两者都保留; - 空值也是值。
EXCLUDE=(空字符串)就是用户关掉默认列表的方式,此后 union 无可叠加。
这些行为全部由 corpus/config/02-merging.kdl 中的测试向量逐条固定。
四、作用域(scope):不是哪都能配
优先级回答"谁赢",作用域回答"谁有资格设"。mise 把 scope 当作安全属性而非偏好:决定代码是否执行的配置项,绝不允许被一个 pull request 就能加进来的文件设置。
| scope | 可来自 |
|---|---|
any(默认) |
任何地方 |
global |
不可来自仓库能携带的任何文件 |
env |
永远不可来自文件 |
越权值会被单独拒收并告警(out-of-scope),不影响其他配置项。
五、用 explain 追踪值来源 🔍
调试"为什么我的值没生效"时,不必逐层猜。Usage 内置的 explain 命令会为每个配置项打印来源(origin)——注意它记录的是"确切位置"而不是"某种类别":是 EX_JOBS 而不是"环境变量",是 ./hk.toml 而不是"某个文件",因为想改答案的用户需要知道该 unset 哪个变量。
usage explain -f spec.usage.kdl mycli --jobs 8 build a
命令实现见 cli/src/cli/explain.rs。即使解析失败也会以退出码 0 输出报告,方便贴进 bug report。
六、异常不崩溃:告警而不是报错
解析过程中遇到的"坏值"遵循最小破坏原则:
- 未知 key 只是告警(
unknown-setting)而非错误——为新版本写的配置文件在旧版本上必须继续工作; - 某个类型读不懂的值只损失它自己的 key,系统级文件里的一个拼写错误不该让全机器用户都无法启动 CLI;
- 改名(
renamed_to)后旧 key 按原优先级落到新配置项上,并告知用户"我把它读成了什么"。
所有告警以**类型(kind)**而非文案固定,各实现(Rust / Go 等)措辞可以不同,行为必须一致。运行 corpus/config/ 的测试向量即可验证:cargo test -p usage-conformance --test config。
七、相关模块速查
| 想做什么 | 去哪里看 |
|---|---|
| 理解优先级规则(规范) | docs/spec/resolution.md |
| 写 config 块(KDL 语法) | docs/spec/reference/config.md |
| Rust 中声明与解析配置 | docs/rust/configuration.md |
| 解析器实现 | config/src/resolve.rs、config/src/env.rs |
| 官方测试向量 | corpus/config/README.md |
总结
- 优先级顺序固定:命令行 > 环境变量 > 配置文件(近者优先)> 其他来源 > 默认值;
- 高层没值就保留低层值,默认值本身是参与合并的"最底层";
- 集合类配置用
union/deep声明合并策略,策略属于配置项而非某一层; scope是安全边界,越权值单独拒收并告警;- 排查值来源就用
usage explain,每个值都会带上确切出处。
