配置文件格式对比

一句话结论：选型先看目标工具链接受什么。格式之间真正不同的，是数据模型、类型写在字面量里还是靠解析器猜、以及同一份文本会不会读出两种结果。没有既有约束时，扁平用 INI 或 .env，机器读写用 JSON，项目元数据和中小型配置用 TOML，深度嵌套且需要复用再用 YAML。

比较什么

范围限于人维护、通常进版本控制、应用在启动或重载时解析的静态配置文件。运行时动态配置、配置中心和密钥管理不在范围内。敏感值也不会因为换了一种文件格式，就可以进仓库。

这类文件会被反复编辑、diff、评审。对照时看这几项：

1. 人能不能顺手改，注释和 diff 是否干净
2. 能不能表达嵌套、列表和键值
3. 字符串、数字、布尔、日期是写在字面量里，还是靠解析器猜
4. 能不能引用一段共享配置
5. 解析库、编辑器、校验工具是否成熟

常见格式

INI

分区（section）下的扁平键值对，值一律当字符串。

[server]
host = 127.0.0.1
port = 8080

[database]
dsn = postgres://localhost/demo

INI 没有统一的正式标准。注释符号、重复键、转义，不同解析器各写各的。它能撑住结构扁平的工具配置，嵌套一深就不够用。Git 配置文件和 pytest.ini 都是 INI 风格，具体规则仍由各自工具定义。

.env

把环境变量写成文本的一类约定，常见形式是 KEY=VALUE 行。没有跨工具的完整规范。值进进程环境后是字符串，也没有通用的嵌套和类型。

DATABASE_URL=postgres://localhost/demo
LOG_LEVEL=info

十二要素应用主张把部署间会变的配置放进环境变量，但没有规定必须用 .env 文件。.env.development、.env.production 这类命名是框架或加载器的约定，不能当可移植标准。含密钥的 .env 不要提交。

JSON 与 JSONC

RFC 8259 把 JSON 定义成一棵树：对象、数组，加上字符串、数字、布尔和 null。对象的键只能是字符串。没有日期、二进制、注释、引用，也不能表达循环。

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  },
  "features": ["search", "billing"]
}

手写配置时，没有注释、不允许尾逗号，改起来别扭。JSONC（JSON with Comments）是允许注释的方言；VS Code 的配置文件用 JSONC，接受但不鼓励尾逗号。JSONC、JSON5 这类方言文件，不再是任意标准 JSON 解析器都能读的 JSON。JSON 更适合由工具生成和回写、人只偶尔看一眼的配置。

TOML

TOML 1.1.0 的目标是：语义明显、易读，并且无二义地映射到哈希表。名字来自作者 Tom Preston-Werner：Tom’s Obvious, Minimal Language。文件从根表出发，由键值、数组和嵌套表组成一棵树。标量包括字符串、整数、浮点、布尔，以及带时区日期时间、本地日期时间、本地日期、本地时间。没有 null，没有共享引用，也没有循环。规范没有规定表的最大嵌套层数。

name = "demo"

[server.database.pool]
max_connections = 10
timeout = 30

[server.database.pool] 就是 server → database → pool 三层子表。Cargo.toml、pyproject.toml 是典型用例。规则少、类型写在字面量里、注释是语法的一部分。深层嵌套时表头路径会变长，长列表和深层树也不如 YAML 紧凑。

YAML

YAML 的节点只有三种结构，具体类型用标签表示。

YAML 1.2.2 Core Schema 用表中这七个标签；应用还可以用显式标签或自定义 Schema 扩展类型。

YAML 可以用 anchor 和 alias 共享节点：

defaults: &config
  retries: 3
  timeout: 30

service_a: *config
service_b: *config

&config 给节点命名，*config 指向它。三处共用同一份数据，完整 YAML 因此是图；不用引用时，可以把它当树。Kubernetes、Docker Compose 和许多 CI 流水线都用 YAML。

缩进就是语法。有些缩进错误不会报语法错，只是把数据结构改掉了。anchor 与 alias 能少写重复，读和改的成本也会上去。

XML

XML 由元素、属性、文本和命名空间构成，数据模型是一棵带属性的元素树。

<server host="127.0.0.1" port="8080">
  <pool maxConnections="10" timeout="30"/>
</server>

语法严谨，XSD（XML Schema Definition）校验成熟，标记也冗余，手写成本高。它是 Java 和 .NET 生态里的历史主流：Maven 的 pom.xml、Spring 配置、.NET 的 .config 仍大量使用。没有既有生态或 Schema 约束时，新项目通常不会先选它。

代码即配置

Django 的 settings.py、Neovim 的 init.lua、Webpack 的 webpack.config.js，是直接拿代码当配置。

宿主语言里可以写条件、循环、函数，也能做类型检查，表达力远超纯数据格式。代价是配置不再是纯数据。读取它通常意味着执行或解释代码，跨语言处理和静态校验都更困难。

HCL（HashiCorp Configuration Language）是另一路：声明式配置语言。Terraform 语言用块、参数和表达式描述目标状态，支持引用、条件、for 表达式和函数，但不是可执行任意过程的通用语言。

对照总表

哈希表

映射是一组“键 → 值”。YAML 叫映射（mapping），JSON 叫对象（object），Python 叫字典（dict），Java 叫 Map。

程序读配置，就是按名字取值。键值再加上数组表示重复项，已经覆盖绝大多数需求。所以这些格式的数据模型都围着哈希表转，差在哈希表之外的规则：

XML 是例外。子元素是有序列表，不是按键索引；属性和子元素谁表示配置项，也没有唯一答案。要把 XML 映射成哈希表，得额外约定。TOML 官方简介的承诺是“无二义性地映射为一个哈希表”，解析结果不但是哈希表，还是哈希表套成的树。YAML 一旦用了引用，这一条就做不到。

类型从哪里来

JSON 和 TOML 把类型写进字面量："3" 是字符串，3 是数字，true 是布尔，看见就确定。YAML 对裸标量做推断，类型由解析规则判定。INI、.env、XML 没有类型，应用程序拿到文本后再转。

数字上，JSON 的语法不区分整数和浮点；TOML 区分，并且有十六进制、八进制、二进制和 inf / nan。YAML 1.1 还支持六十进制（1:20 解析为 80），1.2 已去掉。特性越多，越要先固定版本和 Schema。

null 也不是谁都有。JSON 和 YAML 有。TOML 刻意没有：键要么存在且有值，要么不存在。INI 和 .env 用空字符串或省略键表示。键的类型也不一样：JSON、TOML、INI、.env 的键只能是字符串；YAML 的映射键可以是任意类型。

在这里比较的六种数据格式里，只有 TOML 的当前核心语法原生定义日期时间字面量，并且区分带偏移日期时间、本地日期时间、本地日期和本地时间。YAML 1.2 Core Schema 不含时间戳；XML 可以靠 XSD 拿到日期时间类型。

类型不能压成一条排名。TOML 的内建标量比 JSON 丰富，YAML 可以用标签扩展，XML 可以通过 Schema 获得完整类型系统，宿主语言配置则继承运行时。更有用的问题是：类型由文本显式决定，还是依赖解析器、Schema 或应用代码。

同一份文本，两种结果

二义性指同一份文本存在不止一种合法解析结果。常见来源有四类。

裸标量的类型猜测。解析器对不加引号的词自行判断类型，规则还随规范版本变。YAML 1.1 里 country: NO 是布尔值 false，1:20 是数字 80（六十进制）；YAML 1.2 Core Schema 里它们都是字符串。解析器若仍按 1.1 规则走，同一裸词就会得到不同类型。

规范未定义的行为。JSON 规定对象键应当唯一，但没说重复键怎么处理。不同解析器可能后者覆盖、前者生效，或直接报错。

解析依赖文本之外的约定。YAML 的类型取决于选用哪个 Schema。XML 映射成键值时，属性与子元素谁表示配置项，没有标准答案。

引用与共享结构。YAML 的 anchor / alias 使解析结果成为图，甚至可以自引用成环。“映射为普通字典”没有唯一定义。常见的 << 合并键来自 YAML 1.1 类型库，不属于 YAML 1.2 Core Schema，支不支持取决于解析器。

TOML 把“无二义地映射为哈希表”写成设计目标，并用这些规则收紧解析自由度：

有两种“多个结果”不要混。TOML 里 [a.b] 表头和点号键 a.b = 1 是同一份结构的两种写法，属于“多个文本 → 同一个结果”，是语法糖。二义性是“同一个文本 → 多个结果”。TOML 只允许前者。

二义性来自解析结果依赖文本之外的东西：解析器对未定义行为的取舍，或 Schema 的选择。

注释

配置进版本控制、接受评审时，注释用来记下“为什么这么配”。RFC 8259 定义的 JSON 语法不含注释。需要注释时，只能写 _comment 这类普通字段，或明确改用 JSONC、JSON5。

数据格式普遍用行注释，因为配置按行 diff。XML 的块注释是标记语言的遗留。YAML 里 key: value#注释 的 # 是值的一部分，key: value # 注释 才是注释——和缩进一样，属于改了语义还不报错的陷阱。JSON 不收录注释，是因为它优先当数据交换格式；TOML 面向人维护的配置，注释从一开始就在语法里。

语法糖

语法糖是同一份结构的多种等价写法。它增加认知和 diff 成本，但不会让同一份文本读出两种结构。若只按等价写法的数量粗略比，顺序大概是 YAML > XML > TOML > INI / .env > JSON。宿主语言代码不适合放进这条序列。

JSON 的值语法选择很少：字符串只能双引号，无尾逗号，无简写。空白、对象成员顺序、字符转义和数字写法仍能写出不同文本；要做稳定哈希或逐字比较，还得另用 JSON Canonicalization Scheme 一类规则。INI 和 .env 基本无糖；仅有的写法差异（: 代替 =、export 前缀）因为格式无标准，并不能当真。

TOML 的糖是给手写用的：嵌套有表头、点号键、内联表三种等价写法；字符串有四种语法；数字支持下划线分组和多进制；TOML 1.1 的数组和内联表都允许尾逗号。YAML 最多：块式与流式两种风格（JSON 是 YAML 1.2 的子集）、多种标量风格、块标量加 chomping 指示符，再加上 anchor / alias。XML 的糖是结构性的：<a/> 与 <a></a> 等价，属性与子元素两种建模，CDATA 与实体引用二选一。

读者得认识所有写法。语义相同的文本可以长得完全不同，diff 变吵，团队往往只能靠 formatter 把输出拧成一种。YAML 的 true/True/TRUE 还在糖这一侧，yes/no/on/off 在 1.1 里已经变成歧义。写法越少，生成器和格式化工具越好统一输出；少糖并不等于文本已经 canonical。少糖通常更利于机器处理，多糖通常更照顾手写。

怎么选

这个领域没有权威排行榜。没有标准组织在追踪配置格式的采用率；GitHub 基于 Linguist 的语言统计会排除 JSON、YAML 这类数据语言；包管理器下载量也无法公平比较内置解析器和第三方依赖。

JSON 同时覆盖数据交换和机器生成配置。YAML 常见于 DevOps 和声明式资源。TOML 常见于项目元数据和中小型应用配置。XML、INI 多见于既有生态。.env 只解决环境变量的本地加载，不表达复杂结构。

Kubernetes API 接受 JSON，日常清单通常写成 YAML。Rust 的 Cargo.toml 和 Python 的 pyproject.toml 则直接把 TOML 写进了工具约定。

参考资料

• RFC 8259：JSON 数据交换格式
• Visual Studio Code：JSON with Comments
• TOML 1.1.0 规范
• YAML 1.2.2 规范
• YAML 1.1 Merge Key 类型
• W3C：XML 1.0（第五版）
• W3C：XML Schema 1.0
• The Twelve-Factor App：Config
• HashiCorp：Terraform 配置语言
• Cargo Reference：The Manifest Format
• Python Packaging：pyproject.toml 规范
• Kubernetes：Objects in Kubernetes