YAML 转 JSON

YAML 转 JSON 做的事情很具体：先把 YAML 解析成内存里的数据结构，再把这份结构按 JSON 的语法重新写出来。数据本身没变，变的只是它的“写法”。YAML 用缩进、短横线、注释来表达层级；JSON 用花括号、方括号、带引号的键。转换是一次重新编码，不是改造：每一个列表、映射、字符串、数字、布尔，在 JSON 输出里都保留同样的语义。

为什么会有这个方向的转换需求

YAML 是人愿意手写的格式——Kubernetes 清单、CI 流水线、Hugo/Jekyll front matter、OpenAPI 规范；JSON 是机器更愿意消费的格式——HTTP 接口、Schema 校验器、JavaScript 运行时、调试控制台。转换发生在这两边的交界处：一份人手写的 YAML 要喂给一个只接受 JSON 的下游，与其改造两端，不如在中间转一次。

真正容易出问题的，不是花括号，而是 YAML 自己的语义

很多 YAML 看起来像普通文本，但真正决定结构的是缩进、列表标记、布尔值、null、引号和特殊语法。像锚点、别名、多行文本这些能力，在转换成普通 JSON 后不一定还能保留原来的写作意图。所以更稳妥的做法是：先确认 YAML 本身结构清楚，再把生成出来的 JSON 当作机器侧结果去审查。

YAML 转换前最值得先看的几个点

如何使用这个工具

1. 先在 YAML 转 JSON 中准备一份有代表性的需要变成更严格机器可读输出的 YAML 配置文件和片段，不要一开始就处理最大或最敏感的真实内容。
2. 执行处理流程并生成可用于结构化审查或下游工具的 JSON 结果后，优先检查缩进、列表标记、布尔值、null 值，以及 YAML 源内容是否已经规范化，再判断结果是否真的可用。
3. 只有当结果已经适合用于接口准备、配置迁移、结构校验和文档到代码的交接，并且不再触发这条风险提醒时，才复制或下载输出：YAML 里的锚点或少见写法在转成普通 JSON 后可能仍需人工复核。

YAML 转 JSON 示例

这个 YAML 转 JSON 示例使用有代表性的需要变成更严格机器可读输出的 YAML 配置文件和片段，展示生成后的可用于结构化审查或下游工具的 JSON 结果，便于你先确认缩进、列表标记、布尔值、null 值，以及 YAML 源内容是否已经规范化，再把同样设置用于真实输入。

示例输入

service: api
retries: 3
enabled: true

预期输出

{
  "service": "api",
  "retries": 3,
  "enabled": true
}

一份小型 YAML 配置与对应的 JSON

# YAML
title: Sample
enabled: true
server:
  host: localhost
  port: 8080
features:
  - search
  - export

// JSON
{
  "title": "Sample",
  "enabled": true,
  "server": { "host": "localhost", "port": 8080 },
  "features": ["search", "export"]
}

注意注释和空行在 JSON 里都没了——JSON 本就没有这些概念。如果某条注释承载了真实信息，应在转换前先挪到 description 字段，不要事后补救。

常见使用场景

YAML 转 JSON 最适合用在需要变成更严格机器可读输出的 YAML 配置文件和片段需要快速变成可用于结构化审查或下游工具的 JSON 结果的场景，尤其是接口准备、配置迁移、结构校验和文档到代码的交接。

• 用于把 YAML 转成适合解析器、接口或校验器的 JSON，服务于接口准备、配置迁移、结构校验和文档到代码的交接。
• 处理重要输入前，可先用示例流程确认缩进、列表标记、布尔值、null 值，以及 YAML 源内容是否已经规范化。
• 当结果符合目标流程后，再复制或下载可用于结构化审查或下游工具的 JSON 结果。

YAML 转 JSON 时容易踩到的边界

YAML 转 JSON 出意外，多数不是工具错了，而是 YAML 接受了一些 JSON 表达不了或解读不一致的写法。提前知道这些点，审查输出会快得多。

• “挪威问题”：早期 YAML 把不带引号的 no 解析成布尔 false。新解析器修正了这点，但旧链路里国家代码 NO 仍可能被误读。
• 未加引号的版本号如 1.10 会被解析为数字 1.1，尾部 0 丢失。版本号在 YAML 里始终要加引号。
• 锚点和别名（&base / *base）在 JSON 里会展开。结果是对的，但不再共享结构，diff 会突然变大。
• 块级字符串用 | 还是 > 决定换行如何保留：转成 JSON 后都是字符串，但内容不同。
• 部分 YAML 解析器允许重复键；JSON 不允许。冲突时，工具通常静默保留后一个值。

YAML 与 JSON 各自的强项对比

使用注意

• 复用可用于结构化审查或下游工具的 JSON 结果前，先检查缩进、列表标记、布尔值、null 值，以及 YAML 源内容是否已经规范化。
• YAML 里的锚点或少见写法在转成普通 JSON 后可能仍需人工复核。
• 当结果会影响生产工作或客户可见内容时，应保留原始需要变成更严格机器可读输出的 YAML 配置文件和片段以便回退和核对。

YAML 转 JSON 参考说明

YAML 转 JSON 的参考说明应始终围绕需要变成更严格机器可读输出的 YAML 配置文件和片段、生成的可用于结构化审查或下游工具的 JSON 结果，以及用于接口准备、配置迁移、结构校验和文档到代码的交接前必须确认的检查点。

• 输入重点：需要变成更严格机器可读输出的 YAML 配置文件和片段。
• 输出重点：可用于结构化审查或下游工具的 JSON 结果。
• 复核重点：缩进、列表标记、布尔值、null 值，以及 YAML 源内容是否已经规范化。

参考资料

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• ECMA-404: The JSON Data Interchange Syntax
• YAML 1.2.2 Specification