JSON、YAML、TOML：配置文件格式怎么选

配置文件格式的选择往往被当成口味问题，但它会长期影响三件事：人改配置时会不会改错、机器解析时有没有歧义、以及工具链能不能直接读。下面把三种主流格式放在同一组维度上比较，最后给出按场景的选择结论。

先说前提：三者都能表达同样的嵌套结构，差别不在「能不能」，而在「表达得多舒服」与「歧义面有多小」。

一、五个对比维度

• 可读性：JSON 靠括号与引号，冗长但结构明确；YAML 靠缩进，最简洁但缩进即语法；TOML 靠方括号分段，介于两者之间；
• 注释支持：JSON 标准不支持注释；YAML 用 #；TOML 也用 #。这一点直接淘汰了 JSON 在「需要写说明的配置文件」场景的适用性；
• 类型系统：JSON 有明确的 string/number/boolean/null/array/object；TOML 额外有日期时间、整数下划线分隔、多行字符串；YAML 的类型推断最激进，也因此最容易出意外；
• 解析歧义：JSON 几乎无歧义；TOML 规范严格、歧义极小；YAML 的隐式类型转换与缩进敏感带来最多的踩坑空间；
• 生态兼容：JSON 是接口默认格式，任何语言开箱即用；YAML 在容器编排与 CI 领域是事实标准；TOML 是 Rust、Python 打包工具的首选。

二、YAML 最容易被低估的三个坑

YAML 写起来最舒服，但它的隐式类型推断规则复杂到超出多数人的预期，以下三类问题在生产环境反复出现：

• 布尔与字符串混淆：yes、no、on、off 在 YAML 1.1 中会被解析为布尔值，与 YAML 1.2 的行为不一致，不同语言的解析器结果可能不同；
• 版本号被当数字：version: 1.10 会被解析为浮点数 1.1，与 1.1 无法区分，必须加引号写成字符串；
• 缩进即语法：制表符与空格混用、复制粘贴时多出或少掉一个空格，都会导致解析失败或结构静默变化，而报错信息常常指向无关的行。

三、JSON 的硬伤只有两个

JSON 的问题很集中：一是不能写注释，二是键名与字符串都要加引号，导致同为配置，字符量比 YAML 多出不少。除此之外它几乎无懈可击——解析规则简单、所有语言都有成熟实现、不会出现类型推断意外。

如果配置文件由程序生成、人工几乎不编辑，JSON 是最省心的选择；如果人工改动频繁且需要写说明，就要考虑支持注释的格式。

四、TOML 的定位

TOML 的设计目标就是「人类的配置文件」：显式的类型、清晰的段落划分、支持注释，同时不像 YAML 那样依赖缩进。代价是深层嵌套的表达会变得笨重——数组套对象套数组这类结构在 TOML 里可读性会明显下降。它最适合结构扁平、以键值对和少量表格为主的配置。

五、按场景的选择结论

• 接口请求与响应、机器生成的数据交换 → JSON，不要引入其他格式；
• 容器编排、CI 流水线、需要多行脚本文本 → YAML，但务必统一缩进为空格、给所有版本号加引号；
• 语言包管理、工具链配置、以键值为主的本地配置 → TOML；
• 需要给使用者写大量说明的配置 → 在 JSON 与 TOML 之间选，优先 TOML；
• 对同一个项目：不要混用三种格式。混用会让「改错了哪个文件」变成排查成本。

六、无论选哪种，都加一道校验

配置格式的错误大多在运行时才暴露，而那时的报错往往指向业务代码。把校验提前到提交阶段最划算：JSON 用 JSON 格式化与校验工具 检查语法与结构，YAML 用解析器加一层 schema 校验，TOML 在构建时解析一次。语法错误的排查方法可参考《JSON 校验失败的 10 个常见原因》。