JSON 和 YAML 都能表达对象、数组、字符串、数字和布尔值,但它们的性格完全不同:JSON 严格、适合机器传输;YAML 宽松、适合人写配置。选错格式,往往不是「能不能解析」的问题,而是注释、类型、合并和排错成本的问题。
语法:一个严格,一个依赖缩进
JSON 的语法只有对象、数组、字符串、数字、布尔和 null,键名必须用双引号,不能有注释,也不能有尾逗号。YAML 用缩进表示层级,支持注释、锚点和别名,字符串通常不需要引号。可读性更好,代价是缩进、冒号和特殊字符更容易出错。
# YAML
name: toolbox
features:
- json
- yaml
owner:
name: Toolbox
active: true
{
"name": "toolbox",
"features": ["json", "yaml"],
"owner": {
"name": "Toolbox",
"active": true
}
}
两者表达的是同一份数据。YAML 里的 # 是注释,JSON 里的 # 只是普通字符;这就是为什么把带注释的 YAML 直接转成 JSON 会丢信息。
类型陷阱:YAML 的“自动推断”
YAML 会把 yes、no、on、off 按 YAML 1.1 推断成布尔值;版本号 1.10 可能被当成数字 1.1;2026-10-27 可能被解析成日期。JSON 没有这些隐式规则,字符串必须显式加引号。做配置时,这种差异会导致「文件里写的是字符串,程序里拿到的是布尔值」。
需要保留前导零、版本号、电话号码或 yes/no 文本时,在 YAML 里加引号:"1.10"、"0123"、"yes"。不要依赖解析器的默认推断。
注释、锚点和复用
JSON 标准不支持注释。团队如果需要在配置里写说明,通常改用 JSONC、JSON5 或 YAML;这些格式不是标准 JSON,不能直接丢给只认 JSON 的解析器。YAML 还支持锚点 &defaults 和别名 *defaults,可以做配置复用,但合并规则(尤其是 <<)在不同解析器里并不完全一致。
跨语言、跨服务传数据时,建议用 JSON:所有语言都有稳定实现,字段名和类型明确,调试时也更容易肉眼检查。人写部署配置、CI、Kubernetes 时,YAML 的注释和复用更有价值。
互转时会丢什么
- 注释:YAML → JSON 会丢注释,JSON 没有地方放。
- 锚点和别名:展开成重复结构后,文件会变长;反向转换不会自动恢复复用。
- 键顺序:多数解析器不保证保留,和签名/哈希相关的场景要单独约定。
- 大整数:JSON 数字进入 JavaScript 后可能超过安全整数范围;订单号应使用字符串。
- 重复键:YAML 允许重复键但行为依实现而异,JSON 解析器通常保留最后一个;不要依赖这种输入。
用 YAML ↔ JSON 转换 做一次性转换可以,但不要把转换结果直接覆盖生产配置。先 diff,再确认注释、类型和键顺序是否符合预期。
安全边界
YAML 的反序列化在某些语言里可以构造任意对象,历史上出过反序列化漏洞。不要解析不受信任的 YAML;如果只是数据交换,优先 JSON。JSON 也不是绝对安全:超深嵌套、超大数组和恶意正则都可能拖垮服务,需要限制大小和深度。
怎么选
| 场景 | 建议 |
|---|---|
| HTTP API、前后端数据 | JSON |
| Kubernetes、CI、部署配置 | YAML |
| 需要注释和复用 | YAML 或 JSONC(明确工具链支持) |
| 跨语言、强类型、可机器校验 | JSON + JSON Schema |
| 人工编辑但又要严格校验 | YAML 写,CI 里转 JSON 校验 |
无论选哪个,都把「格式」和「校验」分开:格式负责可读,schema 负责约束。用 JSON 格式化 检查语法,用 JSON 转 TypeScript 生成类型,再决定是否需要 YAML 的注释能力。