YAML 格式化与校验器，免费

什么是 YAML？

YAML（YAML Ain't Markup Language）是一种人类可读的数据序列化格式，用于配置文件（Docker、Kubernetes、GitHub Actions、Ansible）、数据交换等。它使用缩进代替大括号，是 JSON 的超集。

常见问题

校验器能检测哪些错误？

缩进错误、缺失冒号、重复键、无效字符、未闭合字符串、错误嵌套以及其他 YAML 语法问题。错误消息包含行号。

可以将 YAML 转换为 JSON 吗？

可以！点击「→ JSON」按钮将您的 YAML 转换为格式化良好的 JSON。要进行反向转换，请使用我们的 JSON → YAML 转换器，免费。

YAML快速入门

YAML 1.0由Clark Evans、Ingy döt Net和Oren Ben-Kiki于2001年发布；YAML 1.1于2005年发布，当前版本为YAML 1.2.2，修复了若干历史遗留问题（尤其是「挪威问题」，详见下文），并被设计为JSON的严格超集。官方规范位于 yaml.org/spec/1.2.2。本格式化工具使用开源 js-yaml 库，默认按YAML 1.2模式解析，因此大多数1.1遗留特性不会在此触发，但在您输出所发往的大多数服务端YAML工具中仍然适用。

YAML的实际应用场景

YAML已成为云原生基础设施的配置格式标准。最常见的使用场景：

• Kubernetes清单：每个Pod、Deployment、Service、ConfigMap、Ingress都是YAML文档。Helm Chart是包裹Go模板语法的YAML。
• CI/CD工作流：GitHub Actions、GitLab CI、CircleCI、Bitbucket Pipelines、Drone、Jenkinsfile（声明式流水线）、Argo Workflows。
• Docker Compose：多容器应用定义。
• Ansible剧本：配置管理的行业标准。
• 静态网站生成器：Jekyll的 _config.yml、Hugo的 config.yaml、Eleventy的各种配置文件。
• OpenAPI规范：REST API契约，通常以YAML编写，仅在需要时转换为JSON。
• 应用配置：Spring Boot的 application.yml、Rails数据库配置、许多Python和Go服务。

空白字符陷阱（仅用空格）

YAML使用缩进表示结构，规范明确指出制表符不允许用于缩进。只能使用空格。这是手写YAML中最常见的错误来源，尤其是因为许多编辑器会根据设置静默混用制表符和空格。严格解析器给出的错误信息大致为「找到了制表符，无法开始任何词法单元」，即「您在某处使用了制表符」。通用修复方法：在编辑器中启用「显示空白字符」选项，并将所有制表符转换为两个或四个空格。

缩进大小是惯例而非规范。2个空格是Kubernetes清单、GitHub Actions及现代Web中大多数YAML的事实标准。4个空格在Ansible中更为常见。真正重要的规则：在单个文件内保持一致。在同级键之间混用2和4个空格才会导致解析器出错，而不是您选择哪种大小。

挪威问题（以及为何应为有歧义的字符串加引号）

YAML 1.1（仍是PyYAML、snakeyaml及许多其他服务端解析器的默认版本）将一长串未加引号的布尔拼写解释为真正的布尔值：true、True、TRUE、false、False、FALSE、yes、Yes、YES、no、No、NO、y、n、on、off。著名陷阱：挪威的ISO国家代码是NO。若YAML配置将国家列为未加引号的字符串，挪威将被静默解析为布尔值 false，之后读取 countries[0] == 'NO' 的代码会莫名其妙地失败。

YAML 1.2（及js-yaml的默认模式）将布尔值限制为仅 true 和 false，在解析器层面修复了挪威问题。但许多实际工具为了向后兼容，仍默认使用YAML 1.1模式。防御性习惯：对任何看起来可能是布尔值、数字、日期或版本号的字符串加引号：country: "NO"、postal_code: "01234"、version: "1.10"、time: "10:30"。引号是万能的消歧符。

其他类型强制转换陷阱

• 六十进制数（YAML 1.1）。未加引号的 10:30 会被解析为整数630（10乘以60加30）。任何看起来像时间的值都需要加引号。
• 八进制数。在YAML 1.1中，未加引号的 012 会被解析为整数10（前导零的八进制解释）。以零开头的美国邮编、员工ID、邮政编码必须加引号：zip: "01234"。
• 版本号浮点数。未加引号的 1.10 会被解析为浮点数 1.1。请始终为语义版本字符串加引号：version: "1.10"。
• 科学记数法。1e5 会被解析为数字100000。如果您确实希望表示字符串「1e5」（如产品编号、内部ID），请加引号。
• 超大整数。基于JavaScript的YAML解析器（包括js-yaml）在处理超过2⁵³−1的整数时可能损失精度。对于64位ID，请以字符串形式传输。

块样式与流样式

YAML支持两种相同数据的表示法：

# Block style (the standard, indentation-based)
person:
  name: Alice
  tags:
    - admin
    - billing

# Flow style (JSON-like inline)
person: { name: Alice, tags: [admin, billing] }

块样式是99%手写YAML中常见的形式，也是使该格式可读的原因。流样式是一种实用的逃生通道，适用于短的单行值或程序化生成YAML时（无需跟踪缩进）。格式化工具无论输入使用哪种样式，均将输出规范化为块样式（可读性更强的形式）。

锚点与别名（DRY技巧）

YAML的复用特性：使用 &name 锚点定义一次值，在其他位置用 *name 别名引用。对于同一值块多次出现的长配置文件非常便利。

defaults: &defaults
  region: us-east-1
  log_level: info

production:
  <<: *defaults
  log_level: warn   # override

staging:
  <<: *defaults

几点注意：并非所有YAML处理器都支持锚点和别名（尤其是一些较旧的Kubernetes清单工具和某些Helm上下文）。上面展示的 <<: 「合并键」语法是YAML 1.1的扩展，在1.2中已被正式弃用；js-yaml支持它，但纯1.2解析器可能不支持。

多文档文件

单个YAML文件可包含多个文档，用 --- 分隔。常见于Kubernetes：一个文件包含Deployment、Service和ConfigMap，各用 --- 分隔，通过一条 kubectl apply -f 命令应用：

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
---
apiVersion: v1
kind: Service
metadata:
  name: app-svc

YAML vs JSON vs TOML

• JSON：对机器友好，不允许注释，使用括号。通用API载荷格式。
• YAML：对人类友好，允许注释，基于缩进，对人类容易出错。云原生工具的通用配置格式。
• TOML：对人类友好，允许注释，INI风格，比YAML更不容易出错（对于扁平配置）。Cargo（Rust）、Hugo、Black（Python）、Poetry、现代Pip均使用TOML。

如果新配置有选择：扁平配置用TOML，深度嵌套且生态已标准化时用YAML（如Kubernetes、Ansible），机器生成时用JSON。当人类需要读取深层嵌套配置并编写有意义的行内注释时，YAML是正确的格式。

隐私

YAML配置文件中经常包含不应经过第三方服务器的密钥：Kubernetes Secret的base64数据块、application.yml 中的数据库密码、CI工作流中的API密钥、部署配置中的内部主机名。格式化工具完全在您的浏览器中通过开源js-yaml库运行，粘贴的内容在本地解析并重新输出，不进行任何网络请求/上传/日志记录。关闭标签页即清除所有内容。

常见错误

1. 缩进中混用制表符和空格。最常见的错误。规范禁止制表符；部分编辑器会静默插入它们。在编辑器中显示空白字符。
2. 同级键之间缩进不一致。同级键必须对齐到同一列。混用2/4空格缩进会导致解析失败。
3. 未加引号的值看起来像布尔值、数字、日期或时间。NO、012、1.10、10:30、yes：请加引号。
4. 冒号后缺少空格。key: value 有效；key:value 无效（会被解析为单个字符串）。
5. 行尾空白字符。部分解析器将行尾空格视为有意义的内容，部分则不然。跨工具安全的做法是去除行尾空白字符。
6. 多行字符串未使用正确的块标量。长字符串需要 |（字面量，保留换行）或 >（折叠式，合并行）。纯文本未加引号的多行内容很少按预期工作。
7. 假设锚点/别名到处可用。Helm和某些Kubernetes上下文不完全支持 &/*。请在真实流水线中测试后再依赖它们。
8. 编码不匹配。YAML文件应使用UTF-8。使用UTF-16 BOM保存的Windows编辑器文件会让部分解析器无法读取。

更多常见问题

格式化工具会保留我的注释吗？

不会。js-yaml库将YAML解析为JavaScript值后再从该值重新输出，这意味着注释（如 # like this）会被丢失，它们存在于源文本中而非解析结构中。如果保留注释很重要（对手工维护的配置文件通常如此），请使用支持注释保留的替代方案，如通过其CST API使用 eemeli/yaml，或手动进行小幅编辑，而非通过本格式化工具往返处理。

为什么我的 NO 被服务端YAML解析器当作布尔值处理？

因为该解析器使用的是YAML 1.1（PyYAML、snakeyaml等的默认版本），它将 NO 解释为布尔值 false。本格式化工具默认使用YAML 1.2（通过js-yaml），因此在此处不会触发该问题，但一旦将文件发送到YAML 1.1环境，陷阱就会激活。请始终为有歧义的字符串加引号：country: "NO"。

可以将YAML转换为JSON吗？

可以，点击「→ JSON」按钮即可。对于所有可在JSON中表示的内容（字符串、数字、布尔值、null、数组、对象），转换是无损的。无法保留的内容：注释（JSON无此语法）、锚点和别名（JSON无等价物），以及YAML的日期/时间戳类型（在JSON中转为字符串）。反向转换请使用专用的JSON转YAML工具。

内容会发送至服务器吗？

不会。所有解析、格式化和JSON转换均通过js-yaml在您的浏览器中运行。粘贴的YAML不会传输至任何服务器。这一点很重要，因为YAML配置文件经常包含敏感信息（Kubernetes Secret值、数据库密码、API密钥、内部端点），不应上传至第三方服务。

大小限制是多少？

没有硬性限制，格式化工具在您浏览器的内存中运行。典型的Kubernetes清单（几KB）和Helm Chart（几十KB）格式化几乎是即时的。非常大的多文档文件（数MB）可能较慢，但通常可以运行；如果您有一个10MB的Helm Chart，建议改用本地CLI工具格式化。

为什么YAML这么容易出错？

三个相互叠加的原因：（1）有意义的空白字符意味着拼写错误会导致静默的语义变化；（2）YAML 1.1宽松的类型强制转换会将有歧义的字符串变为意外的布尔值/数字；（3）该格式有太多方式表示同一事物（块样式与流样式、单引号与双引号、三种多行字符串写法）。防御性习惯：始终加引号、始终保持缩进一致、部署前验证，可以解决大部分问题。

相关工具