技术英语 / 系统课时

处理 CI 失败与补充说明

处理 CI 失败与补充说明

CI 失败并不等于你的代码一定有问题。真正需要做的是先判断失败来自本次改动、运行环境,还是项目已有的不稳定检查,再把证据、结论和下一步动作清楚地写进 PR,避免维护者重复排查。

学习目标

  • 按证据区分代码问题、环境问题和已知不稳定项
  • 用最小步骤复现并验证与自己改动相关的失败
  • 用简洁英文记录排查结论、修复动作和仍需确认的问题

先判断失败属于哪一类

看到红色 CI 后,不要直接修改代码。先打开失败的 job,定位第一个真正失败的步骤,并确认它是否执行到了与你修改内容相关的测试、构建或静态检查。

常见情况可以分为三类:代码问题通常能稳定复现,而且错误位置与本次修改相关;环境问题常表现为依赖下载、网络、权限、缓存或 runner 异常;已知不稳定项则往往随机失败,重新运行后通过,或仓库已有 Issue、历史记录说明同一检查存在 flaky 情况。

CI 失败分类与处理流程

用最小检查确认是否是本地改动

在执行项目自己的测试命令前,可以先确认工作区中到底有哪些修改,以及补丁是否存在明显的空白字符错误。下面两条 Git 命令不依赖具体语言或构建工具,适合做第一轮排除。

bash
# 查看当前未提交修改,确认没有混入无关文件
git status --short
# 检查补丁中的尾随空格等常见格式问题
git diff --check

预期输出:如果工作区只有预期修改,第一条命令会列出对应文件;如果补丁没有空白字符错误,第二条命令不会输出内容。例如:

text
 M src/example-file

接下来应运行仓库贡献指南或 CI 配置中已经定义的测试、构建或 lint 命令。不要根据其他项目经验猜一个命令,因为本地验证只有与仓库实际 CI 步骤一致时才有意义。

如果失败能在相同提交上稳定复现,而且错误明确指向你修改的逻辑,应先修复代码再推送。如果本地无法复现,则继续比较 CI 与本地的操作系统、运行时版本、依赖版本和环境变量,而不是立即改业务逻辑。

用证据识别环境问题和 flaky 检查

环境问题的关键特征是:失败发生在业务测试真正开始之前,或者错误与代码语义无关。例如依赖仓库超时、磁盘空间不足、服务启动失败、访问凭据缺失,都更接近 CI 基础设施问题。

对于疑似 flaky 的测试,不要只凭“重新跑一次就过了”下结论。至少比较失败 job 与成功 job 的测试名称、报错位置和提交 SHA;如果仓库已有相关 Issue、维护者评论或历史失败记录,再把它作为已知不稳定项引用。

在 PR 中补充英文排查说明

维护者最需要知道的是“发生了什么、你查了什么、现在还需要什么”。不必写成长篇故障报告,可以按结论、证据、动作三个部分组织。

代码问题已经修复时,可以写:

The CI failure was caused by my change. I reproduced it locally, fixed the failing case, and pushed an updated commit. The relevant checks now pass locally.

判断为环境问题时,可以写:

I checked the failed job and it appears to be an environment-related failure rather than a test failure from this change. The job failed while downloading dependencies before the affected tests started. I have not changed the code yet and will rerun the check first.

遇到已有记录的 flaky 检查时,可以写:

This looks unrelated to the patch and matches the known flaky failure tracked in #<ID>. The same commit passed after a rerun. I am leaving the code unchanged unless further investigation is needed.

其中 <ID> 应替换为仓库真实 Issue 或讨论编号;没有证据时不要声称某个失败是“known flaky”。

修复后确认闭环

推送修复后,要重新查看原先失败的 job,而不仅仅看 PR 顶部是否变绿。确认之前的失败步骤已经通过,同时检查是否出现新的失败。如果只是 rerun 后恢复,也要保留之前的排查说明,让维护者知道你没有忽略异常。

一个合格的 CI 跟进不要求你解决所有基础设施问题,而是要把责任边界说明白:属于自己的问题就修复并验证;属于环境或已知不稳定项就提供证据、引用记录,并明确下一步是否需要维护者协助。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理 CI 失败与补充说明

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通