YAML 格式化与美化:把乱缩进的配置理顺

写 Kubernetes manifest、GitHub Actions 工作流、docker-compose 的人,大概都被 YAML 的缩进坑过。少一个空格,多一个 Tab,整份文件就解析不动,报错还经常指向错误的行。本文讲清 YAML 美化到底在做什么:怎么对齐缩进、怎么按键排序让 diff 干净、和 JSON 怎么选,以及为什么这类敏感配置最好在本地处理。

缩进必须用空格,不能用 Tab

这是 YAML 规范里写死的一条:缩进只认空格,禁止 Tab。问题在于很多编辑器默认把 Tab 键打成制表符,肉眼看上去和空格一样,解析器却会直接报「found character that cannot start any token」。

正确做法是统一用 2 个空格做一级缩进,层层叠加:

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    environment:
      LOG_LEVEL: info

注意 web: 比 services: 缩进 2 格,image: 又比 web: 缩进 2 格,列表项 - "8080:80" 的 - 也对齐在 ports: 内层。4 空格也行,但全文必须一致,不能这段 2 格那段 4 格。格式化工具会把整份文档重排成统一档位,顺手把混进来的 Tab 全部换成空格。

一段乱 YAML,格式化后长什么样

下面这段是我从一个真实的 PR 里抄出来的,缩进深浅不一,还混了 Tab(下面用 \t 标出),键的顺序也乱:

name: deploy
on:   [push]
jobs:
  build:
        runs-on: ubuntu-latest
        steps:
	- uses: actions/checkout@v4
        - run: make build
env:
   NODE_ENV: production
   CACHE: "true"

build: 下面是 8 格,steps: 里的第一个列表项还顶着一个 Tab,env: 用了 3 格。把它粘进 YAML 美化与校验工具,按 2 空格 Format,得到的是这样:

name: deploy
on:
  - push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make build
env:
  NODE_ENV: production
  CACHE: "true"

缩进全部归到 2 格的整数倍,Tab 没了,on: [push] 这种 flow 写法也被展开成更易读的块样式。整份文件现在能干净地过解析。

按键排序,让代码评审的 diff 只剩真改动

团队协作里最烦的一种 diff:两个人改同一份 300 行的 Deployment,结果 git diff 里冒出 40 行,其中 38 行只是键的顺序被各自的编辑器换了位,真正的改动埋在里面找不到。

打开「键排序」再格式化,工具会递归地把每个 map 的键按字典序重排。两份文件排完序再比,顺序差异被抹平,diff 里只剩真正动过的那几行。这对 lockfile、Helm values、需要长期维护的 manifest 特别管用。

有个坑要记住:排序会把锚点(&name)和别名(*name)的文本名字去掉,值被内联到原引用位置。结构关系还在,但如果下游有脚本按锚点名字去 grep,排完序就找不到了。这种情况就别勾「键排序」。

YAML 和 JSON 怎么选

YAML 适合人写人读的配置:支持注释、缩进表达层级、不用满屏括号引号。JSON 适合机器之间传输:语法严格、没有缩进歧义、几乎所有语言都原生解析。

实际场景里两者常常要互转。比如你想把一段 YAML 塞进一个只认 JSON 的 API,或者反过来想把一坨难读的 JSON 配置变成带缩进的 YAML 来 review。这时候用 YAML 与 JSON 互转工具比手改靠谱,它会保留结构、处理好类型转换。

还有个细节值得提:YAML 1.2 规范下,yes、no、on、off 都是普通字符串,只有 true / false 才是布尔。但 1.1 时代的工具链会把 on 强转成布尔 true,GitHub Actions 文件里的 on: 键就可能被悄悄改名。保险写法是加引号写成 "on":。

本地处理,密钥不出标签页

docker-compose.yaml 里有数据库密码,.env.yaml 里有 API token,Helm values 里有证书。这类文件如果丢进一个会把内容 POST 到服务器的在线校验器,等于把密钥交了出去。

我自己的习惯是:凡是带敏感信息的配置,只用纯前端、不上传的工具校验。把真文件直接粘进去,确认 services: 下的缩进能解析、键的层级对,在 docker compose up 报错之前就把出问题的那行改掉,整个过程一字节都不离开浏览器标签页。关掉页面,什么都不留。这点对线上配置尤其重要,毕竟一次误传可能就是一次事故。

小结

YAML 美化不只是让文件好看:统一空格缩进让它能解析,键排序让 review 的 diff 干净,和 JSON 的取舍决定你用哪种格式传输。把这几件事交给一个本地运行的工具去做,比手抠缩进既快又稳。下次再被一个混进来的 Tab 卡住 CI,粘进去点一下 Format 就好。

Made by Toolora · Updated 2026-06-13