CI/CD / 系统课时
排查构建失败
排查构建失败
构建失败最容易被“直接重试”掩盖,真正高效的做法是按固定顺序缩小问题空间。本节使用环境、依赖、缓存、权限、资源五层排查法:先保留失败现场,再找到最早出现异常的一层,修复后用原始构建命令复验。
学习目标
- 按环境、依赖、缓存、权限、资源的顺序定位构建失败
- 用一次诊断脚本留下可比较的版本、依赖、缓存和资源证据
- 区分根因与伴随症状,并设计可靠的修复后验证
先保留失败现场
出现失败时先记录原始失败命令、退出码和首个错误位置,不要立即清空工作区或连续重试。随后保存 Runner 镜像、工具链版本、锁文件、缓存键、工作目录权限和资源余量;这些信息决定问题能否在另一台 Runner 上复现。
如果同一提交“昨天能过、今天失败”,优先怀疑执行环境或外部依赖变化;如果只有某个 Runner 失败,则优先比较镜像、缓存和权限。先做差异比较,比从最后一行错误日志开始猜原因更稳定。
按五层顺序执行诊断
下面的脚本适用于常见 Linux Runner 和 Node.js 项目。它不会在某一层失败后立即退出,而是把每层输出写入独立日志,并在终端打印退出码,便于快速找到最早的异常层。
#!/usr/bin/env bash
set -u
run_check() {
local name="$1"
shift
local log="diag-${name}.log"
"$@" >"$log" 2>&1
local rc=$?
printf '%s exit_code=%s log=%s\n' "$name" "$rc" "$log"
return 0
}
run_check environment bash -lc 'uname -a; node --version; npm --version'
run_check dependencies bash -lc 'test -f package-lock.json && npm ci --ignore-scripts --no-audit --no-fund'
run_check cache bash -lc 'npm cache verify'
run_check permissions bash -lc 'test -r package.json && test -r package-lock.json && test -w .'
run_check resources bash -lc 'df -Pk .; command -v free >/dev/null && free -m || true; ulimit -n'预期输出
environment exit_code=<VALUE> log=diag-environment.log
dependencies exit_code=<VALUE> log=diag-dependencies.log
cache exit_code=<VALUE> log=diag-cache.log
permissions exit_code=<VALUE> log=diag-permissions.log
resources exit_code=<VALUE> log=diag-resources.log<VALUE> 会随 Runner 状态变化。通常应先查看最早出现非零退出码的层,再打开对应的 diag-<name>.log;后续层的失败可能只是前面问题造成的连锁症状。

判断每一层常见根因
环境层关注 Runner 镜像、JDK/Node/Python 等工具版本、系统库和关键环境变量。依赖层关注锁文件是否与清单一致、私有仓库是否可达、证书与代理是否变化。依赖安装已经失败时,不要先删除缓存,因为这样会破坏现场证据。
缓存层要做对照实验:同一提交在“使用缓存”和“绕过缓存”两种条件下结果不同,才有足够证据把问题归因到缓存。权限层检查工作区可读写性、制品目录、SSH key 或仓库令牌的有效范围;资源层则检查磁盘、inode、内存、文件句柄和任务超时。
修复后必须回到原始命令
确认根因后只修改对应层,避免一次同时升级工具链、删除缓存、改权限和扩容 Runner。先用原始提交、原始构建命令和尽量相同的 Runner 条件复验;通过后再重复运行至少一次,确认不是偶然成功。
如果问题只在 CI 出现而本地无法复现,应把诊断脚本产出的版本与资源信息和成功 Runner 做差异比较。构建排障的终点不是“这次绿了”,而是能够说明失败发生在哪一层、证据是什么、修复改变了什么,以及相同条件下为什么不会再次失败。