命令行 > 环境变量 > 配置文件 > 默认值:Usage 配置解析优先级完全指南

原创2026-10-15 19:20:021,668 阅读

命令行 > 环境变量 > 配置文件 > 默认值:Usage 配置解析优先级完全指南

用 Usage 定义 CLI 时,同一个配置项可能同时出现在命令行参数、环境变量、配置文件和默认值里,到底听谁的?这份完整指南讲清 Usage 配置解析优先级的 5 层规则、合并策略、作用域限制,以及用一条命令追踪"值到底从哪来"的实用技巧。

Usage CLI 配置解析优先级完全指南

一、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,每个值都会带上确切出处。
登录后查看全文
usage