TOML vs YAML vs JSON：配置文件格式实用对比

配置文件格式为何重要

配置文件是软件与运维人员之间的接口。糟糕的格式选择会带来摩擦：晦涩的语法错误、意外的类型转换、版本控制中糟糕的差异对比，以及新团队成员陡峭的学习曲线。三种主流的基于文本的配置格式以不同方式解决了这些问题。

JSON

JSON（JavaScript Object Notation）最初是为数据交换而非人工编写的配置文件而设计的。后来因其普遍性和严格的解析规则而被用作配置格式。

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "timeout": 30
  },
  "database": {
    "url": "postgres://localhost/myapp",
    "pool_size": 10
  }
}

优点：

• 通用工具支持——每种语言都有 JSON 解析器
• 严格且无歧义：无类型猜测，无隐式转换
• 非常适合机器生成的配置（Prettier、ESLint、package.json）
• 版本控制中差异对比可读性极佳

缺点：

• 不支持注释——这是配置文件的一大痛点
• 语法冗长（每个键需要引号、逗号、括号）
• 多行字符串需要笨拙的转义
• 尾随逗号是语法错误（尽管 JSONC 修复了此问题）

最佳适用场景：npm/package.json、VS Code 设置、语言工具配置、消费者是代码而非人类的 API。

YAML

YAML（YAML Ain't Markup Language）专为人类可读的配置而设计。它优先考虑最少的标点符号和自然的表达方式。

server:
  host: 0.0.0.0
  port: 8080
  timeout: 30

database:
  url: postgres://localhost/myapp
  pool_size: 10

# 原生支持注释
feature_flags:
  new_dashboard: true
  beta_api: false

优点：

• 原生支持注释
• 最少的标点符号——大多数字符串无需引号
• 多行字符串支持 |（字面量）和 >（折叠）
• 锚点和别名实现 DRY 配置
• 广泛用于 DevOps（Docker Compose、Kubernetes、GitHub Actions、Ansible）

缺点：

• 缩进敏感：一个多余的空格就会破坏文件
• 类型推断可能带来意外：port: 8080 是整数，但 version: 1.10 可能被解析为 1.1
• 挪威开发者问题：在 YAML 1.1 中 no 被解析为布尔值 false
• 复杂特性（合并键、多文档）增加认知负担

最佳适用场景：Docker Compose、Kubernetes 清单、CI/CD 流水线（GitHub Actions、GitLab CI）、Ansible playbook、Hugo/Jekyll 静态站点。

TOML

TOML（Tom's Obvious Minimal Language）由 Tom Preston-Werner（GitHub 联合创始人）于 2013 年创建，专门作为一种无歧义、可读且可预测的配置格式。

[server]
host = "0.0.0.0"
port = 8080
timeout = 30

[database]
url = "postgres://localhost/myapp"
pool_size = 10

# 原生支持注释
[feature_flags]
new_dashboard = true
beta_api = false

优点：

• 显式类型：字符串需要引号，数字不需要，布尔值为 true/false
• 不依赖缩进：结构由 [section] 标题定义
• 支持注释
• 一流的日期/时间类型：2026-05-21、2026-05-21T09:00:00Z
• 无歧义：无意外类型转换

缺点：

• 工具支持不如 JSON 或 YAML（但正在快速改善）
• 表数组语法不够直观
• 不适合深层嵌套结构
• 未使用过 Rust 或 Cargo 的开发者不太熟悉

最佳适用场景：Rust 项目（Cargo.toml）、Hugo 配置、Python 工具（pyproject.toml、poetry）、任何优先考虑配置文件正确性而非生态惯例的项目。

并排对比

你应该选择哪种？

选择 JSON 当：

• 文件由工具而非人类编写（package.json、.eslintrc）
• 严格的模式验证是优先考虑
• 你需要最大的语言/工具兼容性

选择 YAML 当：

• 你在 Kubernetes、Docker 或 GitHub Actions 生态中工作
• 你的团队已在使用 YAML，一致性很重要
• 你需要内联注释用于文档

选择 TOML 当：

• 你在构建 Rust 项目（Cargo.toml 是标准）
• 你想要可预测的类型解析，没有意外
• 你的配置有许多设置，受益于节标题

格式转换

如果你继承了一个使用某种格式的项目，并希望迁移到另一种格式：

→ TOML 转 JSON — 将 TOML 配置转换为 JSON → TOML 转 YAML — 将 TOML 转换为 YAML → YAML 转 JSON 转换器 — 将 YAML 转换为 JSON → YAML 转 TOML — 将 YAML 转换为 TOML → JSON 转 TOML — 将 JSON 转换为 TOML