实战：排查 CI 失败

Claude Code CI 失败排查教程：先判断失败阶段是安装、构建、测试、Lint、类型检查还是部署，不要只看最后一行。

排查模板

CI 失败和本地构建失败很像，但多了环境差异：Node 版本、缓存、密钥、权限、系统平台、工作目录都可能不同。先看失败阶段，再看第一处真正错误。

/debug

CI 失败了，请帮我排查。

失败日志：
【粘贴关键日志】

要求：
1. 判断失败发生在哪个阶段。
2. 找到第一处真正错误。
3. 判断是否和本次修改有关。
4. 给出最小修复方案。
5. 不要顺手修复历史问题。
6. 修复后说明本地如何验证。

给 CC 的信息越完整越好

• CI 平台：GitHub Actions、GitLab CI、Vercel、Netlify、Jenkins 或其他。
• 失败 job 名称。
• 失败 step 名称。
• 第一处 error 附近的日志。
• 本次 PR 或提交改了什么。
• 本地是否能复现。

请只读分析这次 CI 失败。

CI 平台：【填写】
失败 Job：【填写】
失败 Step：【填写】
本次改动摘要：【填写】
本地是否复现：【能 / 不能 / 未尝试】

日志：
【粘贴从失败 step 开始到第一处 error 后的一段日志】

请先判断失败阶段和根因，不要直接改代码。

常见分类

• 依赖安装失败。
• 构建失败。
• 测试失败。
• Lint 或格式化失败。
• 部署权限或密钥失败。

先让 CC 把失败归到一个阶段，不要把 CI 全部重写：

每类怎么判断

依赖安装失败

常见原因是 lock 文件不一致、registry 网络问题、Node 版本不一致、私有包权限不足。不要一上来删除 lock 文件。

构建失败

通常和代码、类型、路径、环境变量有关。先确认本地能不能复现同一个构建命令。

测试失败

先看是本次改动引入的行为变化，还是测试环境依赖时间、随机数、网络、数据库状态。

Lint 或格式化失败

这类通常可以最小修复，但也要避免格式化全项目导致 diff 爆炸。

部署权限或密钥失败

这类不要让 CC 打印真实密钥。只让它分析缺哪个变量、在哪个环境配置。

本地和 CI 不一致怎么办

CI 失败但本地正常，很常见。不要直接改业务逻辑，先让 CC 找差异：

本地正常，但 CI 失败。请先分析差异，不要修改文件。

请检查：
1. Node 或运行时版本是否不同。
2. 包管理器和 lock 文件是否一致。
3. CI 工作目录是否正确。
4. 是否缺少环境变量或密钥。
5. 是否有大小写路径、平台差异或缓存问题。
6. 本地应该如何模拟 CI 的最小检查。

如果本地也能复现，处理方式就回到构建失败或测试失败的流程。

让 CC 给修复计划

请给出 CI 失败修复计划，不要直接改。

请输出：
1. 失败阶段。
2. 第一处真正错误。
3. 是否可能由本次修改引入。
4. 本地复现方式。
5. 最小修复方案。
6. 需要人工检查的 CI 配置或密钥。

如果涉及 CI 配置文件，让 CC 解释每一处改动：

如果需要修改 CI 配置，请先给方案。

要求：
1. 说明要改哪个 job 或 step。
2. 说明为什么这一步会失败。
3. 说明改动是否影响其他分支或部署环境。
4. 不要打印真实密钥。
5. 不要删除安全检查、测试或 lint，除非明确说明风险并等待确认。

修复后怎么验收

请验证 CI 修复是否可靠。

要求：
1. 本地运行和 CI 对应的最小检查。
2. 说明本地结果能否代表 CI。
3. 如果 CI 依赖密钥或平台权限，请说明人工复查点。
4. 不要把历史失败一起修掉，除非我确认。

CI 的最终通过往往需要平台重新跑一次。本地验收可以证明一部分，但不能替代所有 CI 条件：

看到这些要拦住

• 删除测试或 lint 来让 CI 变绿。
• 直接把密钥写进仓库。
• 删除 lock 文件但没有解释。
• 改 CI 工作流影响所有分支却没说明。
• 把部署失败当成代码失败乱改业务。

验收结果

• 能定位失败阶段。
• 能区分历史问题和本次问题。
• 修复方案最小。
• 能说明本地验证和 CI 验证的关系。