JSON 转 YAML 在线转换：语法差异、转换规则与常见坑

JSON 格式化工具 · 2026-09-13

YAML 是 JSON 的「超集」：任何合法 JSON 都是合法 YAML，但反过来不成立。把 API 返回的 JSON 转成 YAML 写进配置文件（docker-compose、k8s、GitHub Actions）非常常见，但直接复制粘贴十有八九踩坑。本文讲清转换规则和高频错误。

JSON 与 YAML 语法差异对照

转换示例

// 原始 JSON
{
  "name": "deploy",
  "image": "nginx:1.25",
  "ports": ["80:80", "443:443"],
  "env": {"DEBUG": true, "LOG": null},
  "args": ["--reload"]
}

# 转换后的 YAML
name: deploy
image: nginx:1.25
ports:
  - "80:80"
  - "443:443"
env:
  DEBUG: true
  LOG: null
args:
  - --reload

转换时必须遵守的规则

1. 键后面冒号必须跟一个空格：name:deploy 是错的，name: deploy 才对
2. 统一缩进：同一层级用相同数量空格，禁止混用 Tab
3. 数组项以 - 开头并对齐：- 后也要有空格
4. 布尔与 null 小写：YAML 里是 true / false / null（虽然大写也能解析，但保持小写最稳）

常见踩坑

1. 冒号出现在值里

值里带冒号会被误解析成键值对，必须加引号：

# ❌ 报错
command: echo: hello

# ✅ 正确
command: "echo: hello"

2. 看起来像数字或布尔的字符串

port: "8080" 与 port: 8080 类型不同；flag: "yes" 在 YAML 1.1 里会被解析成布尔 true。这类值统一加引号最保险。

3. 多行字符串

JSON 里用 \n，转成 YAML 推荐用块标量：| 保留换行、> 折叠成一行：

script: |
  echo "hello"
  echo "world"

4. 缩进错位

YAML 对缩进零容忍，少一个空格就解析失败。粘贴后先用 yamllint 或在线校验跑一遍。

5. 锚点与重复引用

YAML 支持 JSON 没有的「锚点复用」，这也是很多人转过来后喜欢它的原因：

defaults: &defaults
  retries: 3
  timeout: 5s

api:
  <<: *defaults   # 继承 defaults
  path: /v1

注意这个特性 JSON 做不到，所以「YAML 转 JSON」时锚点会被展开成具体值，结构不变但少了抽象。

6. 日期与时间戳

YAML 会把 2026-09-13 直接解析成日期类型，而 JSON 里它只是字符串。跨系统传递时统一加引号写成 "2026-09-13"，避免接收方拿到的类型不是你预期的。