JSON 转 YAML：完整迁移指南

JSON 和 YAML 用不同的语法表示相同的数据结构。在大多数情况下，两者之间的转换很简单，但类型、多行字符串和注释方面的边界情况需要注意。本指南涵盖了两种格式之间的完整映射。

语法映射

对象 / 映射

JSON：

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  }
}

YAML：

database:
  host: localhost
  port: 5432
  name: myapp

数组 / 序列

JSON：

{
  "servers": ["web1", "web2", "web3"]
}

YAML：

servers:
  - web1
  - web2
  - web3

嵌套结构

JSON：

{
  "services": [
    {
      "name": "api",
      "ports": [8080, 8443],
      "env": {"NODE_ENV": "production"}
    }
  ]
}

YAML：

services:
  - name: api
    ports:
      - 8080
      - 8443
    env:
      NODE_ENV: production

使用我们的 JSON 转 YAML 转换器 即时转换。

需要注意的边界情况

1. 注释

YAML 支持注释；JSON 不支持。将 YAML 转换为 JSON 时，所有注释都会丢失：

# 这条注释在 JSON 中会丢失
database:
  host: localhost  # 这条也会丢失

2. 多行字符串

YAML 有强大的多行语法，而 JSON 没有：

description: |
  This is a multi-line
  string that preserves
  line breaks.

在 JSON 中，这变成：

{
  "description": "This is a multi-line\nstring that preserves\nline breaks.\n"
}

3. 类型歧义

YAML 自动检测类型，这可能导致问题：

version: 1.0    # 浮点数，不是字符串 "1.0"
port: 080       # 八进制数 64，不是字符串 "080"
country: NO     # 布尔值 false，不是字符串 "NO"

在 JSON 中，类型是明确的：

{
  "version": "1.0",
  "port": "080",
  "country": "NO"
}

将 JSON 转换为 YAML 时，对可能被误解的值添加引号。

4. 空值

两种格式都支持 null，但语法不同：

value: null     # 显式
value: ~        # YAML 简写
value:          # 空值 = null

{ "value": null }

5. 键中的特殊字符

JSON 键可以包含任何 Unicode 字符。YAML 中包含特殊字符的键需要加引号：

"content-type": "application/json"  # 连字符需要引号
simple_key: value                    # 下划线没问题

命令行转换

使用 yq（YAML 处理器）

# JSON 转 YAML
yq -P input.json > output.yaml

# YAML 转 JSON
yq -o=json input.yaml > output.json

使用 Python

# JSON 转 YAML
python3 -c "import json, yaml, sys; print(yaml.dump(json.load(sys.stdin), default_flow_style=False))" < input.json > output.yaml

# YAML 转 JSON
python3 -c "import json, yaml, sys; print(json.dumps(yaml.safe_load(sys.stdin), indent=2))" < input.yaml > output.json

联合使用 jq + yq

# 处理 JSON，输出为 YAML
cat config.json | jq '.database' | yq -P

何时使用哪种格式

使用 JSON 的场景：API 通信、数据存储、机器生成的配置、浏览器环境。

使用 YAML 的场景：人工编辑的配置、Docker Compose、Kubernetes、CI/CD 管道、Ansible。

如需更深入的对比，请参阅我们的 YAML vs JSON 文章。

常见问题

YAML 是 JSON 的超集吗？

是的，自 YAML 1.2（2009）起，每个有效的 JSON 文档也是有效的 YAML。YAML 解析器可以直接解析 JSON。但反过来不成立——YAML 的注释、锚点和多行字符串等特性在 JSON 中没有对应物。

JSON 和 YAML 哪个解析更快？

JSON 在几乎所有语言中的解析速度都明显更快。JSON 解析器更简单，因为格式的语法更少。对于启动时只加载一次的配置文件，差异可以忽略不计。对于高吞吐量的数据处理，JSON 是明确的选择。

相关资源

• JSON 转 YAML 转换器 — 即时转换格式
• YAML vs JSON — 详细的格式对比
• YAML 语法教程 — 从零开始学习 YAML