JSON 转 YAML 转换器

在浏览器中将 JSON 转 YAML，YAML 转 JSON

JSON 和 YAML 描述的是同一类数据 — 嵌套的映射、列表、字符串、数字和布尔值 — 但它们外观迥异，用途各不相同。只要你的工作离不开 API、容器文件或 CI 流水线，迟早会需要把一种转成另一种。本页面可以双向完成这种转换，且完全在你的浏览器内运行，因此你粘贴的数据绝不会离开你的机器。

JSON 是什么，又用在哪里

JSON（JavaScript 对象表示法）是一种严格的、以方括号和大括号构成的格式，首要面向机器。每个对象都用 {} 包裹，每个数组用 [] 包裹，键和字符串值都加双引号，各项之间用逗号分隔。它是 REST 和 GraphQL API 的默认传输格式，是大多数 webhook 的请求体，是 NoSQL 文档的形态，也是你的 fetch 调用所返回的东西。几乎每种语言都开箱即用地解析它，这正是它拿下 API 层的原因：JavaScript 里的 JSON.parse、Python 标准库里的 json，以及其他各处的对应实现。代价是 JSON 手写起来繁琐，且禁止注释，因此它并不适合给人整天编辑的文件。

YAML 是什么，又用在哪里

YAML（YAML Ain't Markup Language）的设计取向恰恰相反：以人为先。它去掉了大括号和引号，用缩进来表达嵌套，还允许你用 # 写注释。正是这种可读性使它成为配置领域的通用语言。Docker Compose 文件、Kubernetes 清单、GitHub Actions 和 GitLab CI 工作流、Ansible playbook，以及数不清的应用配置文件，全都是 YAML。一份典型的 YAML 文档明显比等价的 JSON 更短，在拉取请求中也远更易于比对差异。这份优雅的代价是脆弱，而这正是转换变得有趣的地方。

真正要紧的关键差异

有三处差异几乎决定了所有的转换抉择。第一，空白在 YAML 中具有意义，而在 JSON 中毫无意义。YAML 用空格 — 绝不用制表符 — 来表示结构，所以一个错位的空格就能悄无声息地改变文档的含义。JSON 则根本不在乎缩进。第二，YAML 支持注释，JSON 不支持。当你生成 JSON 时，YAML 里任何 # 注释都会直接消失，因为没有地方安放它。第三，YAML 拥有更丰富的隐式类型推断。它会欣然识别日期、时间戳以及多种写法的 null，并从未加引号的值中猜测类型。JSON 的类型集小而明确，毫无歧义。另请注意，JSON 在技术上是 YAML 1.2 的一个子集，这也是为什么合法的 JSON 通常能被干净地当作 YAML 解析，但反过来却不能保证。

需要留意的转换陷阱

往返转换并不总是无损的，了解它在哪里会出问题很有价值：

• 挪威问题。在 YAML 1.1 规则下，未加引号的 NO 会被解析为布尔值 false，而 yes、on 和 off 也会变成布尔值。一个国家代码或一个开关标签可能在你察觉之前就翻转成了 true/false。把你想当作字符串的值加上引号。
• 数字强制转换。像 3.10 这样的版本号可能会丢掉末尾的零而变成 3.1，而 1.0 即便你本想要文本也会变成数字。给版本字符串和 ID 加上引号。
• 锚点和别名会消失。YAML 的 &anchor 和 *alias 引用在 JSON 中没有对应物。一款好的转换工具会把它们展开成完整的值，因此数据是正确的，但去重就没了 — JSON 转 YAML 再转回 JSON 不会重建出原来的锚点。
• 注释和块标量。转成 JSON 时注释会被丢弃。多行块标量（| 和 >）会塌缩成带 \n 转义的普通 JSON 字符串，因此视觉上的排版意图就丢失了。
• 转回 YAML 时的缩进。JSON 不编码缩进，所以转换工具会挑选一种一致的风格。在粘贴进对制表符敏感的工具之前，请先检查一下。

为什么本地运行很重要

配置文件和 API 载荷恰恰是那种不该上传到某个随机服务器的东西：它们常常携带主机名、令牌、内部服务名或客户数据。本转换工具在你的浏览器中用 JavaScript 完成解析与生成这一步。没有任何内容会被发送到后端，没有任何内容会被记录，而且页面加载完成后该工具可离线工作。粘贴一个 Kubernetes secret 或一份 CI 工作流，尽可放心，它会留在你的机器上。

需要相关工具吗？浏览完整的 数据转换工具 集合，用 JSON 格式化工具 整理凌乱的输入，每当你需要在 API 世界和配置世界之间切换时，随时回到这里。

常见问题