YAML转JSON — 何时转换、如何工作，以及什么会丢失

几年前帮一个团队把CI/CD流水线从一个平台迁移到另一个平台。旧系统用JSON定义流水线，新系统用YAML。理论上不是大问题——两种格式都描述相同的层级数据，对吧？

实际上，我花了大量时间手动把括号改成缩进、删除键的引号、记忆JSON的null在YAML里是~还是null（取决于解析器心情）。这是繁琐且容易出错的工作。最终有人给我指出了一个转换工具，我真切地觉得自己没有从一开始就用它真是太蠢了。

这种经历很常见。YAML和JSON在现代开发中随处可见——CI配置、Docker Compose、Kubernetes清单、API响应、包元数据——它们的重叠足够频繁，总有需要在它们之间转移数据的时候。

YAML和JSON到底是什么

两者都不是编程语言，而是数据序列化格式——将结构化数据表示为文本的方式，让不同系统能够读写。

JSON（JavaScript对象表示法）在2000年代初期被设计为Web客户端和服务器之间发送数据的轻量级XML替代品。它严格、最小化、明确：每个字符串都要引号，每个对象都要花括号，每个数组都要方括号，只有六种值类型（字符串、数字、对象、数组、布尔值、null）。没有注释，没有多行字符串（不转义的话），没有引用之前定义的值的方式。

YAML（YAML Ain't Markup Language——是的，递归首字母缩写）之后出现，明确为人类可读性而设计。用缩进表达嵌套，在大多数情况下允许不加引号的字符串，用#支持注释，有锚点和别名可以定义一次值并在多处引用。YAML 1.2将自身定义为JSON的超集，意味着任何有效的JSON文档也是有效的YAML。

实际上，JSON是当与API通信需要可靠的机器间通信时使用的格式。YAML是人类编写和维护配置时使用的格式——缩进比括号扫描更快，注释在配置文件中非常有价值。

什么时候实际需要转换

CI/CD平台迁移：不同平台有不同偏好。GitHub Actions用YAML，一些旧的Jenkins配置用JSON或XML。在它们之间移动时，流水线定义需要转换。

Kubernetes和REST API：kubectl愉快地接受YAML，Kubernetes API本身用JSON工作。如果通过curl直接对API编写脚本，需要JSON。如果为人类读取并提交到git编写清单，想要YAML。

配置文件和应用默认值：许多应用以JSON提供默认配置（因为是机器生成的）但以YAML记录文档（因为人类读文档）。

调试API响应：API返回JSON。有时想检查响应、编辑它并重放——用YAML有时更容易阅读。

YAML转JSON转换器实际做什么

在底层，转换分两步：将YAML解析为内存中的数据结构，然后将该结构序列化为JSON。

YAML锚点和别名被解析。YAML让你用&anchor定义一个值，并在别处用*alias引用它。转换为JSON时，锚点消失了——引用的值只是在使用它的每个地方内联重复。结果JSON是正确的，但更冗长。

类型推断发生。YAML做隐式类型。裸true变成布尔值，42变成整数，3.14变成浮点数，2026-04-21在某些解析器中变成日期。JSON没有日期，规范中也没有整数与浮点数的区别——只有"数字"。

注释被丢弃。这是最痛苦的损失。解释为什么超时设置为30秒或某个神秘标志做什么的有用注释，在转换后消失了。JSON没有注释语法，没有办法绕过这个。

麻烦的部分：YAML 1.1对比1.2的布尔值问题

在YAML 1.1中，以下值都被视为布尔值：

true, false, yes, no, on, off
TRUE, FALSE, YES, NO, ON, OFF
True, False, Yes, No, On, Off

这意味着完全无辜的YAML键enabled: yes变成JSON中的"enabled": true。而country: NO——也许是挪威的ISO国家代码？——变成"country": false。

YAML 1.2在2009年发布，通过将布尔值限制为只有true和false来修复了这个问题。但令人惊讶的是，许多YAML解析器仍然实现1.1规则。

安全规则：在任何可能被转换的YAML文件中，给任何看起来像布尔值的字符串加引号。如果想要字符串，写country: "NO"和enabled: "yes"。这是导致追踪三小时、修复五秒的那种bug。

转换往返安全吗？

YAML到JSON再到YAML：失去注释、锚点定义（变成重复值），以及原始YAML中的所有格式选择。结果YAML是正确的，但看起来像是机器生成的。

JSON到YAML再到JSON：对标准JSON来说实际上相当安全。由于JSON是YAML的子集，往返保留所有数据。

实用要点：将转换用于单向或同向任务。如果需要同时维护YAML配置和JSON表示，保留一个作为真实来源并从其生成另一个，不要在转换后手动保持两者同步。

使用ToolboxHubs的YAML转JSON工具

YAML to JSON转换器处理上述所有情况：

1. 粘贴YAML — 接受从简单键值配置到深度嵌套的Kubernetes清单的所有内容。
2. 查看JSON输出 — 转换在浏览器中运行，不向服务器发送任何内容。
3. 复制结果 — 点击复制按钮就完成了。

工具处理锚点、多行字符串、所有布尔类型、null值和嵌套结构。还会在输入时验证YAML——如果有缩进错误或格式不正确的文档，你会看到错误消息，而不是静默地输出错误结果。

如果想反向操作，有JSON to YAML转换器。相同原则，方向相反。

何时用YAML vs JSON（观点性建议）

当人类是主要作者和读者时用YAML。配置文件、CI流水线定义、Kubernetes清单——这些存在于版本控制中，被人读取、审查和调试。YAML的可读性和注释支持确实有价值。

当机器是主要生产者或消费者时用JSON。API响应、数据库记录、生成的配置、服务间的数据交换——这些不受益于可读性，因为没有人手动编写它们。JSON的严格性和通用支持才是重要的。

当在边界处——从API接收JSON但配置基于YAML的系统，或相反——转换只是工作流中的一个工具。重要的是理解转换中什么可能改变，并在出错时进行检查。

相关工具

YAML验证器 — 在转换之前，有助于知道YAML是否实际有效。

JSON格式化工具 — 转换后，JSON可能出来是一长行。格式化工具用可配置的缩进美化它。

JSON to YAML — 反向操作，相同工作流。

总结

YAML和JSON都是优秀的数据格式，但适用于不同的场景。在它们之间工作时——人类编写YAML，系统期望JSON，或相反——转换成为日常任务。

YAML to JSON转换器处理机械部分。理解转换中什么会丢失——注释、锚点、格式——这是本文的目标，这样当出现意外时你知道该找什么。