← 全部文章
更新于 May 29, 20266 min read

YAML 格式化器:格式化、重新缩进与校验 YAML

YAML 格式化器会重新缩进并规范化 YAML,让它既可读又便于 diff。学习缩进规则、类型陷阱,以及何时格式化、何时转换为 JSON。

YAML 是空白敏感的，所以一个误入的 tab 或者不一致的缩进不只是看起来乱 —— 它会改变语义甚至让解析直接失败。一个 YAML formatter 能解决这个问题：它把 YAML 重新缩进到一致的深度、规范化空格，并（可选地）排序 key，让文件可读、diff 干净。本指南讲清 YAML formatter 做什么、它强制哪些缩进规则、需要小心的类型陷阱，以及什么时候该格式化 YAML、什么时候该把它转成 JSON。

YAML Formatter 做什么

formatter 把你的 YAML 解析成数据结构，再用一致的风格重新序列化出来。数据不变 —— 只是表现形式被规范化了：

  • 重新缩进 把每一层都改成固定宽度（通常是 2 空格），并把 tab 替换成空格
  • 规范化空格：冒号周围、列表 dash 周围以及内联集合周围
  • 可选地排序 key，得到一个 canonical、利于 diff 的顺序
  • 顺带做校验 —— 解析不过就意味着你有语法错误要先修
# 之前 —— 缩进混乱，难扫读
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# 之后 —— 2 空格缩进，规范化
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

为什么要格式化 YAML

  • 可读性 —— CI pipeline、Kubernetes manifest 和 Docker Compose 文件嵌套得很深，一致的缩进让它们容易扫读。
  • 干净的 diff 与 review —— 规范化的格式（加上排序 key）意味着 PR 只会展示真正的变更，而不是空白噪音。
  • 尽早发现错误 —— 只有合法 YAML 才能被格式化成功，所以 formatter 顺便就是一次快速合法性检查。
  • 团队风格一致 —— 一套风格自动应用，而不是每个作者各自的缩进习惯。

Formatter 强制的缩进规则

YAML 大多数错误都是缩进错误，而这正是 formatter 会标准化的部分：

  • 只用空格 —— 永远不用 tab。 YAML 禁止用 tab 字符做缩进。一个 tab 是最常见的「为啥解析不过？」YAML bug。
  • 深度一致。 同级 key 相对父节点必须缩进相同的空格数。formatter 把所有东西都改写到一个固定宽度。
  • 列表对齐。 块序列（-）里的元素要在 key 下面对齐；formatter 会规范化 dash 是缩进的还是齐平的。

重格式化时的类型陷阱

格式化保留数据，但当值没有加引号时，YAML 的类型推断还是可能让你大吃一惊 —— 在你完全信任输出前值得了解：

  • 「Norway problem」。 没引号的 NO、yes、 on、off 可能被读成布尔值，于是国家代码 NO 就变成了 false。这种值要加引号，保持为字符串。
  • 前导零和大数。007 如果被当成数字读会丢掉前导零；非常大的整数会丢失精度。必须保持为字符串的 ID 要加引号。
  • 日期和时间戳。 某些 parser 会把没引号、看起来像日期的字符串强转成时间戳类型。需要字面字符串的话就加引号。

Block 风格 vs Flow 风格

YAML 有两种写集合的方式：block（缩进的、面向行的）和 flow（内联的，类似 JSON，用 [] / {}）：

# block
ports:
  - 80
  - 443

# flow（相同数据）
ports: [80, 443]

formatter 通常为了可读性会统一成 block 风格。flow 风格兼容 JSON —— 在只能吃 JSON 的工具链里嵌入 YAML 时很有用 —— 但层级一深就难扫读。

锚点（Anchor）和别名（Alias）：可复用片段

& 标记一个 anchor；* 引用它。在不复制粘贴的前提下，在多个服务之间共享配置时很有用，formatter 会保留它们：

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

注意：把 YAML 转成 JSON 时，anchor 和 alias 会 消失 —— JSON 没有引用类型，所以那些值会被内联展开。YAML → JSON → YAML 往返一圈就丢了。

超出解析的 Lint：yamllint

formatter 规范形态；yamllint 强制风格规范（行长、key 顺序、文档起始标记、truthy 值、注释间距）。在 CI 里把它们成对用：先 format，再用团队挑的规则 lint。

格式化 YAML 还是转成 JSON

格式化让文件保持 YAML —— 适合还要给人继续编辑的情况。转成 JSON 是为了程序消费它（大多数应用运行时只解析 JSON）。由于 YAML 1.2 是 JSON 的严格超集，数据上是无损转换；见 把 YAML 转成 JSON 和 JSON vs YAML，了解什么时候用哪个。

在浏览器里格式化并校验 YAML

把你的 YAML 粘到 fixjson 的 YAML 校验器与格式化工具，点 Format YAML 来重缩进与规范化，或者点 To JSON 转成 JSON。它会报告任何语法错误的精确行号，而且一切都在你的浏览器里跑 —— 不上传 —— 对含主机名、密钥或内部设置的配置文件尤其重要。

常见问题

YAML formatter 做什么？

它把你的 YAML 解析后再用一致的缩进与空格（可选还排序 key）重新序列化出来，让文件可读、对 diff 友好。数据不变 —— 只是格式被规范化了。

为什么我的 YAML 解析不了？

几乎总是缩进问题：一个 tab 字符（YAML 不允许 tab 作缩进），或者同级 key 缩进不一致。formatter 把所有东西都改写成一个基于空格的固定宽度，能把这些问题大都暴露并修掉。

格式化 YAML 会改变我的数据吗？

不会 —— 它只改空白和 key 顺序。不过要小心没引号的值：YAML 会做类型推断（「Norway problem」），所以像 NO 或 007 这类必须保持字符串的值要加引号。

我该格式化 YAML 还是转成 JSON？

需要继续给人编辑就格式化；需要给程序消费就转 JSON。很多团队用 YAML 编写，加载时再转成 JSON。

相关工具与指南