GitHub Actions build 失败常见错误和解决步骤

GitHub Actions build 失败时，新手最容易被红叉吓到，然后开始乱改配置。其实 CI 排查的第一步不是修改，而是定位：哪个 workflow、哪个 job、哪个 step、哪条关键错误。

完整流程可以先看 GitHub Actions build 失败怎么看日志。这一篇专门讲常见错误和修正顺序。

适合谁

适合已经打开 Actions 日志，但不知道哪一行重要的人。你可能只复制了最后的 Process completed with exit code 1，却没看到真正报错在前面。

也适合准备给客户解释 CI 失败的人。客户需要知道失败来自代码、配置、权限还是第三方平台，而不是只听一句“CI 挂了”。

不适合谁

不适合为了让检查变绿而删测试、关 lint、跳过部署步骤的人。短期看红叉消失，长期可能让项目质量更差。

也不适合在没有客户授权时修改 secret、runner、组织策略或部署平台连接的人。这些是权限边界，不是普通代码修复。

风险提醒

不要把日志完整贴到公开地方。日志可能包含客户路径、内部地址、环境变量名、服务名或部署信息。复制给外部工具前先脱敏。

如果你发现 secret 泄漏、token 打印或私有地址暴露，先停下并提醒客户撤销或轮换相关凭据。不要继续把泄漏日志扩散。

具体步骤

错误一：只看最后一行

最后一行常常只是退出码，不是真正原因。你要往上找第一条 error、failed、missing、permission denied、not found 或 test failure。

修正方式：记录失败 step 的第一条关键错误，再复制前后 20 行上下文。

错误二：改错 workflow

一个仓库可能有测试、构建、部署、预览多个 workflow。你看到部署失败，却去改测试脚本，问题不会变好。

修正方式：先记录 workflow 名、job 名和 step 名。确认失败点后再动代码或配置。

错误三：删除检查步骤

有些人为了让 CI 通过，直接删除 lint、test 或 build 步骤。这不是修复，而是隐藏问题。

修正方式：先理解失败原因。如果规则不合理，也要写清楚为什么调整，而不是无记录删除。

错误四：忽略环境变量

很多 build 本地能过，CI 失败，是因为 CI 缺少环境变量或 secret。此时继续改业务代码可能没有意义。

修正方式：确认缺少的变量名、作用范围和配置位置。真实值由客户或仓库管理员在平台侧配置。

错误五：忽略权限和账单

部署失败可能来自平台 token、团队权限、项目绑定、配额或账单状态。它看起来像 CI 失败，实际是外部服务问题。

修正方式：把它列为客户侧确认事项，并说明本地代码是否已经通过可验证命令。

恢复顺序

如果已经改乱了，先停止继续提交。回到失败 run，记录 workflow、job、step、关键错误。然后检查最近一次提交改了哪些文件。最后把问题分成代码修复、配置确认、客户授权三类。

能本地复现的，先本地修。不能本地复现但日志明确缺少 secret 的，写客户确认。涉及部署平台授权的，不要伪造凭据或要求客户把长期 token 发出来。

如果日志泄漏了敏感信息

如果你发现日志里打印了 token、私有 URL、账号信息或客户内部配置，先不要继续把日志转发给更多工具。第一步是截图或记录泄漏位置，第二步提醒客户撤销或轮换相关凭据，第三步再处理 workflow 为什么打印了这些信息。

有些泄漏来自脚本里的 echo，有些来自错误地打印环境变量，还有些来自第三方工具的调试输出。修复时要把“停止打印敏感信息”和“撤销已泄漏凭据”分开处理。

项目新手不要承诺自己能完成全部安全响应。你可以帮助定位日志位置、建议撤销凭据、修改明显的打印语句，但客户账号、组织 secret 和平台权限通常需要客户或管理员处理。

怎么避免再次改乱

修 CI 时每次只改一个原因。比如先处理依赖安装，再处理测试，再处理部署。不要同时改 workflow、依赖版本、环境变量名和业务代码，否则下一次失败时很难判断是哪一处造成的。

每次改完都写一行记录：改了什么、为什么改、用什么命令验证。这个动作有点慢，但能防止你在客户仓库里越修越乱。新手项目练习时，清楚记录比“多试几个办法”可靠得多。

CTA：下一步

先从失败 run 里摘出 workflow、job、step 和第一条关键错误。需要拆日志用 报错解释器，需要整理说明用 模板库。

免责声明

本文是学习和排查流程，不构成法律、安全或职业承诺。真实客户项目需要结合仓库权限、secret 配置、部署平台、组织规则和客户授权人工判断。