GitHub Actions build 失败怎么看日志

GitHub Actions build 失败时，红叉只是入口，真正有用的信息在 workflow、job、step 和错误上下文里。新手不要只把最后一行复制给 AI，也不要立刻修改一堆配置。先看哪一个步骤失败，再判断是依赖、测试、环境变量、权限、缓存还是部署平台问题。

项目场景里尤其要谨慎。CI 失败可能是你代码改坏了，也可能是客户没有配置 secret、仓库权限不足、账单或 runner 限制、第三方服务未授权。你能修代码，但不能替客户凭空补齐平台权限。

适合谁

适合已经能打开 GitHub 仓库和 Actions 页面，但不知道从哪里读日志的新手。你可能看到的是 build failed、npm ci 失败、测试失败、部署失败、环境变量缺失或权限不足。

也适合准备接小单的人。客户常把 CI 红叉说成“项目坏了”，但你要先判断失败点，而不是直接报价说能修完整条流水线。

不适合谁

不适合只想复制一段日志就让 AI 直接改代码的人。日志需要结合仓库、分支、提交、脚本和环境变量判断。

也不适合没有客户授权就修改 workflow、secret、部署账号或组织权限的人。CI 配置通常连接部署、测试和权限体系，不能随意改。

风险提醒

不要把 GitHub Actions 日志里的 secret、token、部署 URL、内部服务地址和客户信息公开贴出去。虽然平台会遮蔽部分 secret，但你仍然要检查日志里有没有敏感信息。

如果失败原因涉及 secret 缺失、部署平台授权、付费 runner、组织策略或环境保护规则，把它写成客户侧确认事项。不要为了让 CI 变绿而绕开测试、删除安全检查或关闭关键步骤。

具体步骤

1. 找到失败的 workflow

先进入 GitHub 仓库的 Actions 页面，找到红色失败记录。记录 workflow 名称、分支、提交 SHA、触发方式和失败时间。不要只写“Actions failed”。

如果一个提交触发多个 workflow，先定位到底是哪一个失败。例如测试失败和部署失败是两种不同问题。

2. 找到失败的 job 和 step

打开失败记录后，看左侧 job 列表。进入红色 job，再找到红色 step。真正的错误通常在这个 step 的展开日志里。

记录格式可以这样写：

Workflow:
Job:
Step:
Command:
First error line:
Last error line:

第一条错误通常比最后一条更重要。最后一条经常只是退出码。

3. 区分错误类型

常见类型包括：

• 依赖安装失败。
• lint 或 test 失败。
• build 命令失败。
• 环境变量缺失。
• 权限或 secret 不存在。
• 部署平台返回错误。
• runner 环境和本地不同。

先分类，再决定动作。不要把所有失败都当成代码 bug。

4. 本地复现能做的部分

如果日志显示 npm run build 或 npm test 失败，可以在本地运行同样命令。先确认 Node 版本、包管理器、锁文件和环境变量要求。

如果本地缺少客户 secret，就不要伪造生产值。可以使用测试值复现结构问题，但真实 secret 需要客户在平台侧配置。

5. 写出下一步判断

修复前先写一句判断：这是代码问题、配置问题、权限问题，还是需要客户补材料。比如“当前失败来自缺少 DATABASE_URL secret，本地代码尚未进入 build 阶段；需要仓库管理员确认环境变量配置。”

这句话能防止你把权限问题当成代码问题，也方便客户快速响应。

交付记录怎么写

交付记录至少包含：失败 workflow、失败 job、失败 step、关键错误、你已复现的命令、判断结果、下一步需要谁处理。如果已修复，还要记录修复文件和验证命令。

客户不一定懂 CI，但能看懂“失败点在哪里、下一步谁负责”。这就是日志排查的交付价值。

修复后怎么复测

修复后不要只看本地命令通过。CI 失败发生在 GitHub Actions，就需要重新触发一次 workflow 或等待新提交触发检查。记录新的 run 链接、状态、失败是否消失，以及是否出现新的失败点。

如果本地 build 已经通过，但 Actions 仍然失败，说明问题可能还在 runner 环境、secret、权限、缓存或部署平台。此时不要急着否定本地修复，而是把本地结果和线上结果分开写。

复测记录可以很短：本地运行了什么、Actions 重新跑了哪一次、当前状态是什么、下一步需要谁确认。这样客户能看见进展，而不是只看到又一次红叉。

CTA：下一步

先打开失败的 Actions run，复制 workflow、job、step 和第一条关键错误。需要拆日志可以用 报错解释器，需要写客户说明可以去 模板库，估算修复范围可以用 项目报价助手。

免责声明

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