YAML 与 JSON 互转指南：哪个更适合写配置文件？

JSON 与 YAML 核心差异

JSON：严格语法、无注释、键必须双引号、仅一种写法，适合程序生成与 API。

YAML：缩进表示层级、支持 # 注释、少引号、多行字符串更友好，适合人类手写配置。

YAML 1.2 规范以 JSON 为兼容子集；实际互转还要看解析器版本（1.1 与 1.2 行为不同）。

{
  "server": {
    "port": 8080,
    "debug": false
  }
}

server:
  port: 8080
  debug: false

哪个更适合写配置文件？

选手写、多注释、K8s / Docker / CI：YAML 更常见，改一个端口不用碰括号逗号。

选机器生成、前后端交换、数据库 JSON 列：JSON 更稳妥，歧义更少。

package.json、tsconfig.json 等前端生态标准文件就是 JSON；.env 则是键值对而非 YAML。

互转时的常见坑

YAML 中 yes/no、on/off 可能被解析为布尔值；JSON 只有 true/false。

纯数字字符串在 YAML 里可能变成数字类型（如前导零、版本号 1.10）。

YAML 锚点 & 与别名 * 在 JSON 中不存在，转换时会展开或丢失复用语义。

Tab 缩进在 YAML 中非法，必须用空格——从编辑器复制时要小心。

命令行与代码互转

yq / js-yaml：yaml → json 常用于 kubectl 输出管道处理。

python -c 'import yaml,json,...' 或 npx js-yaml 适合脚本化。

转换后务必 JSON.parse 校验，再用格式化工具检查嵌套是否符合预期。

# 示例：yq 将 YAML 转为 JSON（需安装 yq）
# yq -o=json '.' config.yaml

Kubernetes 场景的实用建议

仓库里维护 YAML manifest；CI 里可转成 JSON 喂给某些 API 或策略引擎。

不要用 JSON 手写大型 K8s 配置——缺少注释与多行字符串会让 diff 很痛苦。

Secret 里 Base64 字段两种格式都能表达，保持团队统一即可。

选型小结

人读人写、注释多 → YAML；程序产消、契约严格 → JSON。

团队规范写进 README：默认格式、转换工具版本、禁止 Tab。

互转后永远做一步语法校验，避免 silent type coercion 上线。