YAML格式化与校验

如何使用 YAML 格式化工具

1. 把您的 YAML 粘贴到输入框中，例如 Kubernetes 清单、Docker Compose 文件或 CI 流水线配置。
2. 点击校验检查语法。出错时会报告解析器停下的行号和列号。
3. 点击格式化，以一致的缩进和引号风格重新输出整个文档。
4. 点击转换为JSON，查看同样的数据对应的 JSON。
5. 把结果复制回您的项目。

该工具使用开源的 js-yaml 库，完全在您的浏览器中按 YAML 1.2 解析。您的文件不会被上传或存储在任何地方，当文件中包含主机名、凭据或其他机密信息时，这一点尤为重要。

什么是 YAML？

YAML（“YAML Ain't Markup Language”）是一种便于人阅读的数据序列化格式。它不使用括号和花括号，而是用缩进表示结构，用短横线（-）表示列表项，用 key: value 键值对表示映射。它还支持用 # 写注释、多行字符串，以及用于复用值的锚点和别名。

从 YAML 1.2 开始，这种格式被设计为 JSON 的超集，所以几乎任何有效的 JSON 文档同时也是有效的 YAML。这让两者之间的转换变得很容易：YAML 适合手写，而 JSON 是大多数 API 和程序交换数据所用的格式。

由于空白字符本身携带含义，只要一个空格放错位置，就可能在不报任何错误的情况下改变 YAML 文件的结构。校验并重新格式化，可以让您看到解析器实际是如何读取文档的，这往往是找出隐蔽错误最快的办法。

常见的 YAML 错误及解决办法

用制表符缩进。YAML 禁止用制表符（Tab）缩进。请把它们替换成空格；大多数编辑器都能自动完成。

缩进不一致。同级项必须严格对齐。在下面的例子中，image 多缩进了一个空格：

containers:
  - name: web
     image: nginx:1.27

让它与 name 对齐：

containers:
  - name: web
    image: nginx:1.27

冒号后面缺少空格。port:8080 会被读作一个单独的普通字符串，而不是带值的键。请写成 port: 8080。

未加引号的字符串中含有特殊字符。如果一个值以 *、&、!、@、{ 或 [ 开头，或者包含 : 或 #，就需要加引号：

message: "Error: disk full"
pattern: "*.log"

重复的键。一个映射中不能两次出现同一个键。有些解析器会悄悄保留最后一个值；校验器会把它标出来，让您注意到。

隐式类型：YAML 的经典“坑”

YAML 会为未加引号的值猜测类型。在 YAML 1.2 的核心模式下，true 和 false 是布尔值，null 和 ~ 是空值，看起来像数字的内容则是数字。较旧的 YAML 1.1 解析器走得更远，还把 yes、no、on 和 off 当作布尔值，挪威的国家代码 NO 就是这样变成 false 的，这件事非常出名。不同的工具在这方面至今仍不一致，所以任何必须保持为字符串的内容都应加上引号：

使用技巧与最佳实践

• 每一级缩进使用两个空格；这是 Kubernetes、Ansible 和 GitHub Actions 文件中最常见的风格。
• 需要保留换行的多行文本（脚本、证书）用 |，希望各行折叠成一个段落的用 >。
• 转换为 JSON 是确认结构的可靠办法：如果某个值落在了错误的对象里，JSON 输出会让这一点一目了然。如需来回转换，请使用 JSON ↔ YAML转换器。
• 之后还需要整理 JSON？JSON格式化与校验可以对键排序并压缩它。

常见问题

JSON 是有效的 YAML 吗？

在实际使用中，是的。YAML 1.2 做了对齐，使 JSON 文档也是有效的 YAML，所以您可以把 JSON 粘贴到这个工具里，它也能解析。

为什么 YAML 不允许使用制表符？

制表符在不同编辑器中显示的宽度不同，所以看起来对齐的缩进实际上可能并不对齐。规范禁止用制表符缩进，以保证结构没有歧义。

为什么格式化删除了我的注释？

格式化工具会把 YAML 解析成数据，再重新输出。注释不是数据，所以经过这一来一回就丢失了。锚点和别名在解析时就被展开了，所以输出时可能是展开后的形式，或者带有自动生成的名称。

这个工具支持哪个 YAML 版本？

它使用 js-yaml，遵循 YAML 1.2。为 YAML 1.1 解析器编写的文件通常也能用，但 yes 和 no 之类的值会被当作字符串。

更新于 2026-10-17