📚 课程目录第4章配置文件错误

配置文件错误：YAML/JSON等格式问题归纳总结

CI流程启动崩溃，十次里有六次是因为配置文件写错了。你想想看，明明代码跑得好好的，一到流水线就挂，查半天发现只是多了一个空格——这种事我经历过不止一次。说实话，这类问题最气人，因为它不是逻辑错，是格式错。

这一章我们就把CI中常见的配置文件格式错误彻底梳理一下。我个人习惯把错误分成两大类：语法级错误和语义级错误。语法级错误就是解析器直接报错，比如缩进不对、少了引号；语义级错误是格式合法但值不对，比如把字符串写成了数字、字段名拼错。下面我们逐个攻破。

YAML —— 缩进是最容易翻车的地方

YAML 用缩进表示层级关系，不用花括号。听起来简单吧？但实际项目中我见过最离谱的案例：一个同事写了一个 600 行的 CI 配置文件，就因为第 437 行多了一个空格，整个流水线崩了。

常见的 YAML 错误集中在以下几点：

缩进不一致：混用空格和 Tab，或者同一层级缩进不对齐。
字符串引号问题：包含冒号、特殊字符时忘了加引号。
布尔值歧义：yes、no、true、false 在 YAML 1.1 中都被解析为布尔，导致字符串被误转。
多行字符串格式错误：| 和 > 用错。

⚠️ 重点提醒： 我建议团队里统一用 2 个空格作为缩进单位，并且编辑器里设置「将 Tab 自动转换为空格」。另外，可以用 yamllint 在提交前做静态检查——这能拦截掉 90% 的语法错误。

举个例子，下面这段 YAML 就有两个坑：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Run script
        run: echo "Hello, world"
    env:
      MY_VAR: yes   # 问题1：yes 会被解析为 true（布尔）
      MY_FLAG: false # 问题2：false 也是布尔

如果你想保证 yes 和 false 被当成字符串，我习惯这么写：MY_VAR: "yes" 或者 MY_VAR: 'yes'。

JSON —— 严格但不宽容

JSON 语法非常严格，少一个逗号、多一个逗号、末尾多了一个逗号——都不行。我在项目中遇到过：同事写了一个 .json 配置文件，用 Node.js 的 require() 加载时正常，但是 CI 环境用 json.load() 解析就报错。为什么？因为 Node 的 require 允许注释和尾随逗号，但 Python 的 json 模块不允许。

需要特别留意：

尾随逗号：JSON 标准不允许在最后一个元素后面加逗号。
注释：JSON 原生不支持注释，但有些工具或库会扩展支持（比如 VSCode 的 settings.json）。一旦换个解析器就炸。
键名必须双引号：单引号或不加引号都不合法。
字符串内双引号必须转义："She said: \"Hello\""。

💡 避坑指南： 我曾经在 CI 脚本里用 jq . 来校验 JSON 格式，速度快又准确。你也可以在 pre-commit hook 里挂上 jsonlint -q，如果返回非零则阻止提交。

其他格式（TOML、INI、HCL）

除了 YAML 和 JSON，现代 CI 工具还经常用到 TOML（比如 Cargo.toml、pyproject.toml）、INI（GitLab CI 早期版本）和 HCL（Terraform/HashiCorp 生态）。它们各自的坑也不少：

格式	常见陷阱	我的建议
TOML	数组内不能混类型；键名点号会被当作路径分隔符	用 `toml-test` 校验
INI	节名称重复；值中的等号未转义	优先用 `configparser` 的 strict 模式
HCL	块标签引号、变量引用语法错误	用 `hclfmt` 自动格式化

如何高效排查配置文件错误

遇到配置文件导致 CI 崩溃时，我通常按这个顺序排查：

查看解析器错误消息：大多数工具都会告诉你行号和错误类型，先盯住行号。
用官方校验工具跑一遍：比如 yamllint、jsonlint、toml-test。
对比之前能工作的版本：用 git diff 看看改动点，很多时候一眼就能发现多余的空格或删掉的逗号。
在本地环境用相同解析器加载：比如用 Python 的 yaml.safe_load() 或 json.load() 测试。

⚠️ 注意： 不要盲目信任在线校验器。我在项目中遇到过在线 YAML 校验通过了，但 PyYAML 解析却报错的情况——因为在线工具用的库版本不同。最好的做法是用 CI 环境里同一个语言的同一个库去验证。

预防胜于治疗

我始终坚持一条原则：配置文件也是代码，同样需要 lint。在项目里我通常会加一个 pre-commit 配置，像下面这样：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/mirrors-yamllint
    rev: v1.32.0
    hooks:
      - id: yamllint
        args: ['--strict', '-d', 'rules: {line-length: {max: 120}}']
  - repo: https://github.com/pre-commit/mirrors-jsonlint
    rev: v1.0.0
    hooks:
      - id: jsonlint
        args: ['--quiet', '--comments']

只要提交前能自动检查，格式错误基本进不了仓库。等 CI 跑起来才报错，就已经浪费了五分钟——这五分钟你拿来喝杯咖啡不好吗？