构建失败后，先别急着重跑。把失败按环境与依赖、代码与配置、测试与质量门禁、流水线自身四类归位，用最近一次成功构建作基线，比对提交、依赖锁文件和运行环境，逐类用证据排除，再按影响面选择重跑、回滚或修复后重提。恢复后补上失败归因记录、责任人分派和复发监控，同类失败才不会反复出现。
要点总览（TL;DR）
- 构建失败先按症状归入环境与依赖、代码与配置、测试与质量门禁、流水线自身四类，再从分支、提交、环境三个维度判断是单点偶发还是系统性问题。
- 排查以最近一次成功构建为基线，比对提交记录、依赖锁文件和运行环境差异，回到日志定位第一条真实报错，并区分已证实原因与待验证假设。
- 处置分止血与修复：单次偶发可重跑，阻塞多人时回滚到最近成功版本，临时跳过门禁仅限非关键项；修改共享配置、清理缓存、回滚主干前需备份、评估影响并明确停止点。
- 恢复验证按构建通过、产物可用、下游可继续、连续多次稳定四层确认，再关闭失败记录。
- 把失败类型、根因、处置动作与耗时记录下来，配合依赖锁定、门禁调整、失败告警和定期复盘，减少同类失败复发。
构建失败先看哪些症状，范围如何界定
构建失败处理的第一步是判断“坏在哪里、坏了多大”。症状决定排查方向，范围决定处置力度。单分支单次失败通常按偶发处理，先重跑确认；多分支连续失败或全环境失败，则需要按系统性问题排查，避免逐个重跑消耗时间。
常见症状可以归为五类，每类对应的第一手证据不同：
| 症状类型 | 典型表现 | 优先查看的证据 |
|---|---|---|
| 编译报错 | 语法错误、类型不匹配、接口签名变更后调用方未同步 | 构建日志中第一条报错及其所在文件、提交记录 |
| 依赖拉取失败 | 包下载超时、版本解析冲突、私有仓库鉴权失败 | 依赖锁文件差异、仓库地址与凭证配置 |
| 测试不通过 | 单元测试、集成测试断言失败，覆盖率未达标 | 失败用例清单、测试报告、最近一次通过的测试基线 |
| 超时与环境异常 | 构建时长突增、磁盘或内存不足、构建节点离线 | 构建耗时趋势、节点资源监控、环境变更记录 |
| 流水线配置或权限错误 | 步骤找不到、变量未定义、凭证过期、权限不足 | 流水线配置变更记录、凭证有效期、角色权限设置 |
范围界定建议从三个维度同时看：分支维度，是单分支还是全部分支；提交维度，是单次提交触发还是连续多次；环境维度，是单个构建环境还是全部环境。三个维度都指向“单点”时，优先按偶发处理；任一维度出现“面状”扩散，就按系统性问题升级排查。
还需要区分构建失败与部署失败、发布失败的边界。构建失败指代码编译、依赖解析、测试执行或流水线步骤在产出构建产物之前中断；部署失败指构建已通过，但产物在目标环境启动、配置加载或健康检查环节出错；发布失败则更多涉及发布策略、灰度规则或回滚机制。边界清楚，责任人和排查入口才不会错位：构建失败先找提交人与构建维护者，部署失败先看环境与配置，发布失败先看发布流程与策略。
失败原因假设与排除证据
排查时把猜测写成假设，再用证据证实或排除，可以避免“看起来像”的判断直接变成结论。建议按四类原因假设组织排查，每类都对应可核验的证据。
| 原因假设 | 验证证据 | 证实后的典型结论 |
|---|---|---|
| 环境与依赖 | 依赖锁文件与上次成功构建的差异、构建节点资源与镜像版本、私有仓库连通性与凭证有效期 | 依赖版本漂移、缓存污染、节点资源不足或凭证过期 |
| 代码与配置 | 最近一次成功构建到失败之间的提交清单、配置文件变更、接口签名变更 | 某次提交引入编译错误或配置项缺失 |
| 测试与质量门禁 | 失败用例清单、测试报告、门禁阈值设置 | 新增用例暴露缺陷，或门禁规则调整后未同步修复 |
| 流水线自身 | 流水线配置变更记录、步骤执行日志、权限与凭证设置 | 步骤顺序错误、变量未定义、权限不足 |
排查顺序建议固定为：先取最近一次成功构建作为基线，比对提交记录、依赖锁文件和运行环境三项差异；再根据影响面缩小范围，单分支失败优先看该分支的提交与配置，全部分支失败优先看共享依赖、构建镜像和流水线公共步骤；最后回到日志，定位第一条真实报错，而不是被后续连锁报错带偏。
表达上要区分“已证实原因”和“待验证假设”。例如“依赖锁文件在本次提交中被修改，且新版本与构建镜像中的运行时版本不兼容”是已证实原因；“可能是缓存问题”只是待验证假设，需要补充清理缓存后重跑的结果才能下结论。把假设当结论直接回滚或改配置，容易掩盖真实问题，也会让复盘记录失真。
按影响面选择处置步骤
处置分止血和修复两个阶段。止血的目标是尽快恢复流水线可用，修复的目标是消除根因。选择哪种动作，取决于影响面和证据充分程度。
止血动作及适用条件：
- 重跑构建：适用于单分支单次失败、日志显示为网络抖动或节点临时异常、且最近一次成功构建与当前提交差异很小的情况。连续重跑两次仍失败，应停止重跑，转入原因排查。
- 回滚到最近成功版本：适用于失败已阻塞多人合并或下游部署、且根因定位需要较长时间的情况。回滚前确认最近成功版本的产物仍可用，并通知依赖该分支的提交人。
- 临时跳过非关键门禁：仅适用于门禁失败与本次变更无关、且有明确恢复时间点的情况。跳过需记录原因和恢复责任人，关键门禁（如安全扫描、核心测试）不建议跳过。
修复动作按原因类型展开：依赖问题修正版本并更新锁文件，必要时清理缓存后重跑；代码或配置问题由提交人修复后重新提交；流水线步骤与权限问题由构建维护者调整配置并验证。涉及修改共享流水线配置、清理构建缓存、回滚主干分支等破坏性操作时，前置条件包括：备份当前配置或产物、评估受影响的分支与下游环境、通知提交人与发布负责人、明确停止点（例如“回滚后若下游部署仍失败，停止继续操作并升级排查”）。
角色分工建议在处置开始时就明确：提交人负责确认本次变更内容并修复代码或配置；构建维护者负责流水线配置、缓存与节点问题；测试负责人判断门禁失败是否属于真实缺陷；发布负责人决定是否需要回滚以及回滚范围。分工写进失败记录，后续复盘时才能看清每个环节的响应时间。
恢复验证与复发预防
构建显示通过不等于真正恢复。恢复验证建议按四层确认：构建本身通过且日志无异常告警；构建产物可正常下载并校验完整；下游部署或测试环节可以继续执行；连续多次构建保持稳定，而非一次通过后再次失败。四层都满足，才能关闭本次失败记录。
失败归因记录是复发预防的起点。记录至少包含失败类型、根因（区分已证实与待验证）、处置动作、从失败到恢复的耗时、涉及角色。记录的价值在于让同类失败第二次出现时可以直接对照历史处置，而不是从头排查。
| 预防措施 | 具体做法 | 适用条件 |
|---|---|---|
| 依赖锁定与缓存策略 | 锁文件纳入版本管理，缓存按依赖指纹失效，定期清理陈旧缓存 | 依赖拉取失败反复出现时优先落地 |
| 门禁规则调整 | 区分阻断型与提醒型门禁，阈值调整需评审并记录 | 门禁误报或漏报造成多次失败时 |
| 失败告警与责任人分派 | 构建失败自动通知提交人与构建维护者，明确响应时限 | 失败发现依赖人工巡查时 |
| 定期复盘 | 按周或按迭代汇总失败类型分布、平均恢复耗时，识别高频原因 | 失败次数较多或影响交付节奏时 |
这些记录和分派动作如果散落在聊天工具里，复盘时很难还原。ONES 可集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步流水线数据、更新执行状态和日志；流水线与项目关联后，CI/CD 过程可以在项目、迭代和需求中可视化，构建失败对应的提交与工作项也能关联查看。团队可以把失败归因记录、责任人和处置结论沉淀在对应工作项或文档中，复盘时按失败类型和耗时汇总，作为调整门禁规则和缓存策略的依据。具体告警规则和指标口径需结合团队已接入的工具链配置。
常见问题
构建失败后连续重跑几次仍不通过，应该怎么处理？
重跑适用于单分支单次失败、日志显示网络抖动或节点临时异常、且与最近成功构建差异很小的情况。连续重跑两次仍失败，说明失败可能由提交内容、依赖或流水线配置引起，继续重跑只会消耗时间。此时应停止重跑，取最近一次成功构建作基线，比对提交记录、依赖锁文件和运行环境，定位第一条真实报错后再决定修复还是回滚。
什么情况下可以临时跳过质量门禁，跳过之后要补什么？
临时跳过只适用于门禁失败与本次变更无关、且有明确恢复时间点的场景，例如门禁规则本身正在调整。跳过时需记录跳过原因、恢复责任人和恢复时间，并在恢复后补跑一次完整门禁。安全扫描、核心测试这类关键门禁不建议跳过，否则会把风险带到下游部署环节。
构建通过但下游部署失败，算不算构建失败处理的范围？
不算。构建失败指编译、依赖解析、测试执行或流水线步骤在产出构建产物之前中断；部署失败指构建已通过，产物在目标环境启动、配置加载或健康检查环节出错。两者排查入口不同：构建失败先找提交人与构建维护者，部署失败先看目标环境与配置。边界分清，责任人才不会互相等待。
团队失败记录散落在聊天工具里，复盘时怎么还原？
建议把失败类型、根因、处置动作、恢复耗时和涉及角色写进固定的记录位置，并与对应的提交或工作项关联。ONES 可集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步流水线数据、更新执行状态和日志；流水线与项目关联后，CI/CD 过程可以在项目、迭代和需求中可视化，构建失败对应的提交与工作项也能关联查看。团队可以把归因记录和处置结论沉淀在对应工作项或文档中，复盘时按失败类型和耗时汇总。具体告警规则和指标口径需结合团队已接入的工具链配置。
依赖拉取失败反复出现，优先做哪项预防措施？
优先落地依赖锁定与缓存策略：锁文件纳入版本管理，缓存按依赖指纹失效，定期清理陈旧缓存。同时核对私有仓库地址与凭证有效期，避免鉴权过期被误判为网络问题。如果失败集中在门禁环节，再考虑区分阻断型与提醒型门禁，阈值调整需评审并记录。
