GitHub Actions 工作流无效 — YAML 语法错误

症状

遇到“GitHub Actions 工作流无效 — YAML 语法错误”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• GitHub 报告 “Invalid workflow file” 并给出行列
• on: 或含冒号的 if: 值破坏解析
• 加入特殊字符后工作流失效

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

grep -n "" .github/workflows/ci.yml | sed -n '<line>p'

列号指向破坏解析的确切字符，通常是未加引号的冒号。

步骤 2

python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci.yml'))" && echo OK

本地解析错误与 Actions 失败一致，可快速迭代。

常见诱因（按出现频率排序）：

• 未加引号的值含 YAML 特殊字符（: @ * [ ]）
• 缩进不一致扰乱了映射结构
• 形似布尔的字符串（on、yes、off）被解析为布尔值

根因

GitHub Actions 工作流是 YAML。未加引号的冒号、特殊字符、tab 缩进或形似布尔的键都会使文档无效，Actions 在调度任何任务前即拒绝该文件。

修复

为含特殊字符的值加引号，使用空格（绝不用 tab），需要字面量时把 “on”、“true” 加引号，并在 pre-commit 钩子中用 YAML 解析器校验文件。

注意：YAML linter 可能接受 Actions 因 schema 原因拒绝的文档；应同时校验语法与结构。

# ❌ unquoted colon inside a value
# - name: Build: app

# ✅ quoted value
steps:
  - name: "Build: app"
    run: make build
  - name: Run if literal string
    if: github.ref == 'refs/heads/main'
    env:
      FLAG: "true"   # quoted to stay a string

验证

推送并确认工作流被接受且任务运行；在 CI 保留本地 YAML 检查以防回归。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。