YAML 与 JSON 互转

一、最核心的规则：缩进用空格

YAML 用缩进表示层级，且只允许空格，不允许 Tab。同一层级的元素必须对齐，缩进多少个空格没有强制规定（常见 2 或 4），但整个文件要一致。这一条能解释绝大多数「解析失败」：

# 正确
server:
  port: 8080
  tags:
    - web
    - api

# 错误：混用 Tab、同级没对齐
server:
port: 8080

另外 key: value 冒号后面必须有一个空格，port:8080 会被当成普通字符串而不是键值对。

二、类型是怎么被猜出来的

YAML 不像 JSON 那样所有标量都带引号，解析器会按字面量推断类型，这是互转时最容易出意外的地方：

• true / false / yes / no（YAML 1.1）→ 布尔值；null / ~ / 空 → null。
• 8080 → 数字；2026-11-03 → 可能被解析成日期对象而不是字符串。
• 00123 可能被当成八进制；1.0 是浮点。

所以版本号 1.0、开关 on/off、纯数字编号、日期字符串，想当字符串就加引号。一个经典事故是配置里 version: 1.0 转成 JSON 变成 1，或者用户名 no 变成 false。转成 JSON 后务必抽查这些字段的类型。

三、JSON 没有、YAML 有的东西

• 注释：# 开头。JSON 不支持注释，所以 YAML → JSON → YAML 往返一次，注释会全部丢失。要保留说明就别做无损往返，或把说明写进字段名。
• 锚点与别名：&defaults 定义、*defaults 引用、<<: *defaults 合并。转成 JSON 时会被展开成重复内容，体积变大但语义等价；反向转换不会自动收回去。
• 多文档：用 --- 分隔的多个 YAML 文档，JSON 没有对应概念，通常要转成数组或分别导出。
• 块标量：| 保留换行、> 折叠换行，适合塞多行脚本、证书、提示词。

四、互转时的检查清单

① 缩进全是空格、层级对齐；② 需要字符串的标量加了引号；③ 注释是否需要另存；④ 锚点展开后有没有意外的重复键；⑤ 日期、布尔、数字类型是否符合目标系统预期；⑥ 数组与对象的嵌套层级是否一致。特别是 K8s / Compose 这类对类型敏感的配置，一个 true 变成 "true" 就可能让行为完全不同。

做转换时可以用 YAML 与 JSON 互转，左右对照即时看结果；配合 JSON 格式化校验 确认输出是合法 JSON。转换在浏览器本地完成，配置文件不用上传到外部服务。

五、什么时候该用哪个

给人编辑、需要注释和复用的配置文件，YAML 可读性明显更好；机器之间传数据、需要严格类型和广泛兼容，JSON 更稳妥。很多项目的做法是「源配置用 YAML，构建/运行时编译成 JSON」。

小结

记住三件事：只用空格缩进且冒号后带空格；YAML 会猜类型，拿不准就加引号；注释和锚点在转到 JSON 时会丢或展开。转换后抽查几个关键字段，比事后排查配置事故省事得多。