YAML 转 JSON 在 CI 流水线中：为什么它比你预期的更容易出错

Source: Dev.to

为什么 CI 流水线经常需要 JSON

许多 CI 工具只接受 YAML 作为输入，但在内部会将配置转换或转发为 JSON：

• API 需要严格的 JSON
• 模式校验器基于 JSON 工作
• Helm 将 YAML 渲染为 JSON
• 自定义构建步骤会把配置序列化为 JSON

所以即使你的仓库使用 YAML，JSON 几乎总会在下游出现。

隐藏的问题：YAML 的宽容度高于 JSON

YAML 为了人类可读性而设计，这会导致细微但危险的问题。

1️⃣ 重复键（沉默的杀手）

YAML 允许出现重复键而不抛出错误：

env:
  VAR1: value1
  VAR1: value2   # duplicate key

大多数 YAML 解析器会悄悄覆盖第一个值。转换后，JSON 变成：

{
  "env": {
    "VAR1": "value2"
  }
}

流水线通过了，但原本的意图丢失——这是最常见的 CI bug 之一。

2️⃣ 看似合法却破坏逻辑的缩进错误

YAML 的缩进决定结构。乍看之下是合法的：

steps:
name: build
run:
  echo "Building"

不同的解析器可能会错误序列化，或在转换后导致模式校验失败。CI 工具往往在传递之前并未深度验证 YAML。

3️⃣ 锚点与别名无法干净地转换

YAML 支持复用：

defaults: &defaults
  timeout: 30
  retries: 2

job:
  <<: *defaults
  script: make test

转换后，一些工具会：

• 将值内联
• 完全丢弃锚点
• 触发模式校验失败

JSON 没有锚点的概念，结果可能不可预测。

4️⃣ 数据类型在不知情的情况下改变

YAML 会自行推断类型：

enabled: yes

根据解析器的不同，可能会转换为：

{
  "enabled": true
}

如果你的 API 期待的是字符串（"yes"），就会导致兼容性问题。

常见的 CI 转换方式（及其局限）

import yaml, json
json_data = json.dumps(yaml.safe_load(open("config.yaml")))

最佳实践：转换前先校验

在 CI 中将 YAML 转换为 JSON 之前：

1. 校验缩进
2. 检测重复键
3. 确认数据类型
4. 检查最终的 JSON 输出

务必在配置到达 API 或部署步骤之前完成这些检查。

实用的调试技巧（救了我很多次）

当 CI 流水线在转换后失败时，尝试以下操作：

1. 将 YAML 粘贴到 严格的 YAML → JSON 转换器 中。
2. 检查 JSON 输出是否存在：
   • 缺失的字段
   • 被覆盖的键
   • 意外的布尔值或数字

一个好用的浏览器工具是 jsonviewertool.com/yaml-to-json。它完全在客户端运行，能快速发现结构性问题。

何时应完全避免转换？

如果可能的话：

• 全程使用 YAML（例如 Helm → Kubernetes）。
• 当涉及 API 时，直接使用 JSON 编写配置。

转换应是有意为之，而不是偶然产生。

结语

YAML → JSON 的转换并不难，但暗藏危险。大多数因它导致的 CI 失败：

• 不会抛出错误
• 通过了校验
• 之后在生产环境中表现异常

把转换当作 校验步骤，而不仅仅是格式化步骤。你的 CI 流水线——以及未来的自己——都会感激你。

进一步阅读

• YAML vs JSON in APIs & CI pipelines
• Helm toJson pitfalls
• Duplicate key detection in YAML