配置，是整洁的软件碰上混乱现实的地方。格式要为真正编辑它的人而选；优先级只定一套，越朴素越好；程序启动时就做校验；更不要把 YAML 变成编程语言。
🎙️ 发布并录制于： · 更新于 ·
我的默认选择很直接：机器之间流转的数据用 JSON；人手工维护的应用设置用 TOML；小规模的部署注入用 .env 文件；只有周围的工具明确要求时才用 YAML。格式不是可以随便互换的装饰。不同格式，会让不同错误变得容易发生。
# 争论语法之前，先用这张决策表
machine writes and reads it → JSON
humans maintain app settings → TOML
platform injects 5–20 strings → .env
tool ecosystem requires YAML → YAML
need conditions, loops, imports → use code, not configJSON 最大的优点，是几乎所有语言都同意它的含义。它不允许注释，键名必须用双引号，最后一项后面不能留逗号。我不会让运维人员长期维护一份巨大的 JSON 文件，但作为传输格式和自动生成的产物，它很可靠。
{
"host": "127.0.0.1",
"port": 8080,
"features": ["search", "billing"]
}json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes。Node 常见的报错是 SyntaxError: Unexpected token } in JSON at position 42。按步骤修：打开提示的行或位置；检查右花括号或右方括号之前的那一项；删掉末尾逗号；最后运行解析器确认文件能加载，不要只跑格式化工具。YAML 看起来清爽，因为标点少了。代价是结构变得看不见。缩进本身就是数据，大多数解析器禁止制表符，而普通单词还可能因为解析器版本不同，被猜成布尔值、日期或数字。凡是必须保持字符串的值，都加上引号。
service:
host: "127.0.0.1"
port: 8080
mode: "on" # 加引号：必须保持字符串 "on"
release: "2026-07-24" # 加引号：不要解析成日期对象
code: "0017" # 加引号：保留开头的零yaml.scanner.ScannerError: mapping values are not allowed here；其他解析器会说 found character '\t' that cannot start any token。先在编辑器里显示空白字符，把制表符换成空格，再让同级键对齐到同一列，然后重新解析。不要随手乱加空格，直到报错碰巧换了位置。我反对把 YAML 当编程语言。用锚点重复一个代码块还算可以；模板、自定义标签、条件、字符串插值和五层合并，则是穿着配置外衣的代码，还配了更差的调试器。如果配置需要控制流程，就写一个小型、有类型的程序来生成普通配置，并测试那个程序。
文件由人维护时，我会选择 TOML。字符串一眼就是字符串，分节明确，注释也能保留。.env 并不是功能更丰富的竞争对手，它只是向进程环境提供一小组字符串的方便写法。请让它保持扁平，也保持简短。
# config.toml
[server]
host = "127.0.0.1"
port = 8080
[database]
pool_size = 10
ssl = true
# .env — 每个值进入进程时都是文本
APP_PORT=8080
APP_DEBUG=false
DATABASE_URL=postgresql://localhost/appAPP_DEBUG=false，调试模式反而开启。环境变量都是字符串，而许多语言会把任何非空字符串当成真。请读取原始值，统一大小写，只接受 true 或 false，其他内容一律拒绝。不要用通用的真假判断强行转换。配置故障往往不是值无效，而是一个有效值从意料之外的来源赢了。定好顺序，写在设置旁边，并让程序能显示最终值及其来源。我的顺序是：命令行选项最高，其次是环境变量、本地文件、已提交文件，最后才是内置默认值。
# highest priority wins
1. --port 9000 # 本次运行的明确指定
2. APP_PORT=9000 # 部署环境覆盖值
3. config.local.toml # 不提交的本机覆盖值
4. config.toml # 项目共享设置
5. default: 8080 # 应用后备值
# useful startup output
config: server.port=9000 (source: APP_PORT)配置解析器只能证明标点合法，结构规则才能证明值可用。服务接收流量之前，就要检查类型、范围、必填项、未知键，以及字段之间的关系。启动时失败，比处理客户请求时才发现超时时间无效要厚道得多。
# schema-shaped rules, independent of library
server.port required integer, 1..65535
server.host required non-empty string
log.level one of: debug, info, warning, error
request_timeout number greater than 0
production forbids debug = true
unknown keys rejected
ConfigurationError: server.port must be between 1 and 65535; got 70000Additional properties are not allowed ('timout' was unexpected)。按步骤修：拿键名和结构规则对照；把 timout 改成 timeout；重新校验；再把这个错误拼写加入测试样例。静默忽略未知键，会让一个错字变成生产环境谜案。结构错误要写得具体：给出完整路径、预期约束和收到的值。“配置无效”只替程序员省了五秒，却会浪费运维人员半小时。
仓库里的配置文件可以说明要用哪个数据库，但绝不能存密码。把秘密值放进部署密钥库或受保护的环境，提交一份只有假占位值的示例文件，让配置只保存引用。如果解密密钥就放在同一个仓库里，那么加密配置并没有提供保护。
# config.toml — safe to commit
[database]
url_env = "DATABASE_URL"
# .env.example — names and harmless samples only
DATABASE_URL=postgresql://user:password@localhost/app
SESSION_SECRET=replace-with-a-random-value
# .gitignore
.env
.env.*
!.env.examplePush cannot contain secrets。不要只删掉那一行再重试。先撤销或轮换凭据，因为提交历史里仍然有它。然后从当前文件树和相关历史中移除，改用环境变量查找，把文件模式加入 .gitignore，最后再跑一次密钥扫描。只要密钥进入过一次提交，就假设它已经泄露。轮换才是修复，重写历史只是清理。顺序反过来，你可能得到一个看起来很干净的仓库，里面那枚被窃的凭据却仍然有效。
配置被审查的时间，通常比被编写的时间更长。键的顺序稳定，每项独占一行，注释解释原因，也不要制造自动生成的噪声。一个格式哪怕少写三行，只要它藏住了一处权限变化，就是亏本买卖。
# reviewable: one semantic change produces one obvious diff
allowed_origins = [
"https://admin.example.com",
+ "https://reports.example.com",
]
# noisy: generated timestamp changes on every run
-generated_at = "2026-07-23T18:02:11Z"
+generated_at = "2026-07-24T09:41:53Z"这也是不要让 YAML 可编程的另一个理由。审查者应该直接在变更文件里看到部署值，不该在脑中执行散落于四个目录的锚点、模板、环境变量替换和条件判断。
配置失败时，别再盯着你本来想加载的文件。要问正在运行的进程：它打开了哪个路径，解析了哪些字节，最后又是哪一个来源胜出。相对路径、工作目录、文本编码和没有重启的旧进程，比罕见的解析器故障常见得多。
# debug in this order
1. print the absolute config path
2. confirm that file exists for the running user
3. print a checksum, never secret contents
4. parse it with the same library and version as production
5. validate the schema
6. print resolved keys with source names; redact values
7. confirm whether reload or restart is requiredFileNotFoundError: [Errno 2] No such file or directory: 'config.toml'。打印进程的工作目录和解析后的绝对路径。由服务定义传入绝对路径，或者相对于可执行文件解析，不要依赖碰巧启动程序的目录。然后以服务账户身份验证文件权限。Unexpected token '', "{..." is not valid JSON。那个看不见的字符是字节顺序标记。按字节检查文件，把它另存为不带字节顺序标记的 UTF-8，再解析一次。如果文件来自你无法控制的外部来源，就在输入边界明确移除开头的标记，并为这种情况写测试。请按这个顺序做。它能避免大多数配置事故，也能让剩下的事故尽快结束。
# choose
JSON machine-owned, universal, strict
TOML human-owned application settings
.env small set of deployment strings
YAML only when the tool ecosystem requires it
code conditions, loops, imports, computation
# parse safely
JSON double quotes; no comments; no trailing comma
YAML spaces, never tabs; quote ambiguous strings
TOML keep sections shallow and names explicit
.env parse types yourself; every input starts as text
# precedence, highest first
CLI → environment → local file → committed file → default
# startup contract
parse → reject unknown keys → validate types/ranges → report source
# secrets
secret manager / protected env ✓
.env.example with fake values ✓
real credential in Git ✗
leaked credential → rotate first, clean history second
# debugging
absolute path → permissions → checksum → parser → schema → source
changed file, unchanged app → inspect precedence and reload behavior最好的配置系统应该刻意保持无聊：一种格式，一条优先级规则，一套结构约束，有用的启动错误，并且仓库里没有秘密值。有人想给 YAML 加逻辑时，请直接拒绝，把逻辑移进经过测试的代码。