YAML 转 JSON 实战:配置文件、CI 与 K8s 里的缩进与锚点

写配置的时候 YAML 好读,可程序往往只认 JSON。Kubernetes 的 manifest、GitHub Actions 的 workflow、docker-compose 都用 YAML,而一旦要把这些内容塞进某个只收 JSON 的接口、或者当成字面量丢进脚本,就得转一道。这篇把转换里最容易卡住的语法点和缩进坑讲清楚,顺便给一个可以直接复制的例子。

需要立刻动手的,可以先打开 YAML ⇄ JSON 互转,粘进去双向都能转,报错带行号。

为什么要把 YAML 转成 JSON

最常见的是接口边界。比如你的部署写成 120 行 YAML manifest,而要测的准入 webhook 只认 JSON,那就得先转再用 Postman 打过去。第二种是脚本场景,你在写迁移脚本,想把 docker-compose.yml 里的 service 块变成纯 JS 对象,转出 JSON 后直接当字面量塞进 .ts 文件就行。

反方向也有需求。同事甩过来一坨 200 个键的压缩 JSON,问你超时设对了没,这时候转成 YAML 读起来层级铺开,没有逗号和大括号干扰,三层深处那个 timeoutMs: 3000 一眼就找到。两个方向其实是同一类工作:让数据从机器友好的形态切换到人友好的形态,或者反过来。

缩进与冒号:YAML 语法的两根支柱

YAML 靠缩进表达层级,这点和 JSON 用大括号完全不同。同一层级的键必须左对齐,子级往里缩固定的空格数。冒号后面跟空格表示键值对,短横线加空格表示数组项。这套规则简洁,但也意味着一个空格的错位就能让结构整个走样。

举个最小的对照,下面这段 YAML:

service:
  name: api
  port: 7001
  envs:
    - NODE_ENV=production
    - PORT=7001
  replicas: 3

转成 JSON 是这样:

{
  "service": {
    "name": "api",
    "port": 7001,
    "envs": [
      "NODE_ENV=production",
      "PORT=7001"
    ],
    "replicas": 3
  }
}

注意 YAML 里 port: 7001 没有引号,转出来 JSON 是数字 7001 而不是字符串;envs 下面的短横线列表转成了 JSON 数组。这种类型推断是 YAML 的便利,也是后面要讲的坑的根源。

锚点与引用:YAML 独有的复用机制

JSON 没有变量,同一份配置重复的部分只能复制粘贴。YAML 给了锚点(&)和引用(*),还有合并键 <<:,让你定义一次反复用。比如多个服务共享同一组健康检查配置,可以这么写:

default: &health
  path: /healthz
  interval: 10
api:
  <<: *health
  port: 7001
worker:
  <<: *health
  port: 7002

转成 JSON 的时候,锚点和合并键会被展平。api 和 worker 各自拿到 path 和 interval 的实际值,引用关系不再存在,得到的对象已经是解析好的:

{
  "default": { "path": "/healthz", "interval": 10 },
  "api": { "path": "/healthz", "interval": 10, "port": 7001 },
  "worker": { "path": "/healthz", "interval": 10, "port": 7002 }
}

这正是把 YAML 转给脚本用时省心的地方,你不用自己处理引用解析,转换器替你把锚点摊开了。

那些反复踩的缩进与类型坑

第一个是 Tab。YAML 规范明确禁止用 Tab 缩进,从一个自动插 Tab 的编辑器里拷来的配置,往往第一行就挂,报错通常是 did not find expected key 之类。先把 Tab 换成空格,或者把编辑器设成软 Tab。我自己排查 GitHub Actions 失败时,十次里有七八次是 jobs: 下面两个空格还是四个空格混用,人眼根本看不出来,但解析器一下就卡住。

第二个是布尔类型的误判。很多人以为 yes、no、on、off 会变成布尔,但在现代的 YAML 1.2 规范里它们就是普通字符串,转出来的 JSON 是 "yes" 而不是 true。想要真布尔,老老实实写 true 和 false。

第三个是注释。JSON 没有注释语法,所以 YAML 转 JSON 时每一行 # 说明 都会被丢掉。如果某条注释承载了重要信息,转之前先把它挪进一个真正的键里,否则转完就消失了。

一次性把配置链路对齐

转换不是孤立动作。配置文件常常在多种格式之间流动,YAML 转 JSON 之后,你可能还要把 JSON 美化、或者从别的来源把数据拼进来。需要把 JSON 排版整理时,用 JSON 格式化 把缩进和键序理顺再继续。整条链路里每一步都在浏览器本地完成,配置不出标签页,带 token 的内容也不会被写进 URL,适合处理那些不想上传到任何服务器的敏感配置。

把缩进规则记牢、把锚点的展平行为理解清楚,YAML 和 JSON 之间的来回就只是一次粘贴的事。

---

Made by Toolora · Updated 2026-06-13