GitHub Actions build 失败日志检查清单

这份清单用于排查 GitHub Actions build 失败。完整说明见 GitHub Actions build 失败怎么看日志。目标不是快速猜一个命令，而是把失败位置、原因类型和客户确认事项分开。

适合谁

适合能进入 GitHub Actions 页面，但不知道从红叉里提取有效信息的新手。你可以用这份清单把日志变成可复查记录。

也适合项目诊断。客户给你一个失败截图时，你可以先要到 workflow、job、step 和关键错误，而不是直接修改代码。

不适合谁

不适合在没有仓库上下文时承诺完整修复的人。Actions 日志需要结合代码、脚本、环境变量和权限。

也不适合为了让检查通过而删除测试、关闭 lint 或绕开部署步骤的人。CI 是项目质量和协作的一部分，不是只要变绿就结束。

风险提醒

日志可能包含敏感信息。复制给外部工具或写进工单前，先检查是否出现 token、secret、内部域名、客户邮箱、私有仓库路径或部署配置。

如果失败和 secret、组织权限、部署平台授权、账单或 runner 限制有关，写成客户待确认事项。不要擅自要求客户提供长期敏感凭据。

具体步骤

1. 基本信息

• 仓库：
• 分支：
• 提交 SHA：
• workflow 名：
• 触发方式：
• 失败时间：
• 谁触发：

这些信息能避免你排查错分支或错提交。

2. 失败位置

• 失败 job：
• 失败 step：
• step 运行的命令：
• 第一条错误：
• 最后一条错误：
• 退出码：

第一条错误通常用于定位原因，最后一条错误通常只说明命令失败。

3. 依赖安装

• 是否失败在 npm ci、pnpm install 或类似步骤。
• Node 版本是否和项目要求一致。
• 锁文件是否存在。
• 是否有私有包权限。
• 是否使用了缓存。

私有包权限通常需要客户或组织授权，不能靠修改代码解决。

4. 测试和构建

• 是否失败在 lint。
• 是否失败在 test。
• 是否失败在 build。
• 本地是否能复现同一命令。
• 是否需要环境变量才能运行。

本地复现时要记录命令和结果，不要只说“我这里正常”。

5. 环境变量和 secret

• 报错是否提示 missing env。
• secret 名称是否存在。
• secret 是仓库级、环境级还是组织级。
• 是否需要环境保护审批。
• 是否需要客户添加或更新。

你可以告诉客户缺少什么变量，但不要让客户把真实 secret 发到聊天里。

6. 部署平台

• 部署到哪里：
• 是否需要平台 token：
• 是否需要项目绑定：
• 是否需要团队权限：
• 是否因为配额、账单或组织策略失败：

部署平台问题经常不是代码问题。要把它单独列出来。

最低交付记录

最低记录包含：失败位置、关键错误、原因分类、本地复现结果、已尝试动作、客户待确认事项、建议下一步。这样客户能判断你是在排查，而不是盲目试命令。

如果你修复了代码，还要记录验证命令。如果只是确认缺少客户 secret，也要明确写“当前无法继续验证，需要客户在平台侧配置后再复测”。

日志摘录格式

日志摘录不要整段复制几千行。更好的格式是保留失败 step 名称、运行命令、第一条关键错误、前后少量上下文和退出码。这样既能让别人判断，也能减少敏感信息扩散。

如果日志里出现 token、URL、邮箱、内部路径或客户项目名，先脱敏再放进记录。脱敏后要保留问题含义，例如把真实域名改成 example.internal，把真实 secret 名称改成 DEPLOY_TOKEN。

给客户的记录要避免技术堆砌。可以先写一句结论，再附日志摘录。比如“失败发生在部署 step，原因是部署 token 未配置；代码 build 尚未进入验证阶段。”客户通常先需要这个判断。

复测检查

完成修复或客户补齐配置后，要重新跑一次对应 workflow。记录新 run 的链接、触发提交、是否通过、是否出现新的失败 step。不要只说“我改好了”，因为 CI 的最终证据是新的运行结果。

如果客户还没有补 secret 或授权，复测项就写成待办：等待客户配置后再运行。这样可以区分你的诊断已完成，和外部条件还没准备好。

CTA：下一步

把这份清单填到你的排查记录里。需要拆日志用 报错解释器，需要写客户确认消息去 模板库，需要估算修复范围用 项目报价助手。

免责声明

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