cicd Troubleshooting
CI 缓存失效排查方法
CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。
先对比缓存 key 是否变化，再看缓存目录和命中日志，缓存失效多是 key 算错、路径不对或缓存被清理。
Scenario
这篇文章解决什么问题
适用于“CI 缓存失效排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先对比缓存 key 是否变化，再看缓存目录和命中日志，缓存失效多是 key 算错、路径不对或缓存被清理。
Symptoms
典型现象
- CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。
- 相关日志、命令或页面中反复出现 ci、缓存、cache 等关键词。
- 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。
Before Debugging
排查前先确认
- 先确认是流水线配置问题，还是 Runner / 执行环境问题，避免在 YAML 和基础设施之间来回横跳。
- 保留失败 job 的完整日志、触发上下文、分支和 commit，而不是只看最后几行报错。
- 区分本地能复现但 CI 不行的问题，重点对比环境、密钥、缓存和网络差异。
Root Causes
常见根因分层
Runner 离线或标签不匹配
job 一直 pending 通常是可用 Runner 不足、标签没匹配上或 Runner 被并发占满，而不是流水线语法错误。
- 查看 Runner 在线状态和标签
- 确认 job 声明的 runs-on/tags
- 看并发队列和 executor 资源
缓存失效或 key 计算错误
缓存 key 用了时间戳或分支变量、路径没覆盖真实依赖目录，会让命中率为零甚至复用错误产物。
- 用 lockfile hash 做 key
- 核对 cache path 与真实路径
- 看 restore 日志是否命中
构建环境差异
Docker socket 没挂载、网络走不了内网、secrets 没注入、镜像架构不一致，都会让 CI 表现和本地不同。
- 确认 secrets 作用域和变量
- 检查 docker socket 与网络
- 对比本地与 CI 镜像架构
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。CI 缓存失效排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
gh cache list -R owner/repo --limit 30
gh cache delete <cache-key> -R owner/repo2. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
gh cache delete <cache-key> -R owner/repo
du -sh ~/.cache /tmp/.buildx-cache 2>/dev/null
sha256sum pnpm-lock.yaml | head -c 643. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 在 CI 日志里查看 cache 的 restore/save 步骤，确认是否命中以及实际使用的 key。
- 对比 lock 文件或路径 hash 是否变化，确认缓存 key 计算逻辑是否把易变内容算进去了。
- 检查缓存路径配置是否正确，路径不存在或写错会导致存了却读不到。
du -sh ~/.cache /tmp/.buildx-cache 2>/dev/null
sha256sum pnpm-lock.yaml | head -c 644. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 检查缓存路径配置是否正确，路径不存在或写错会导致存了却读不到。
- 用 gh cache list 查看仓库现有缓存条目和大小，过期或损坏的用 gh cache delete 清理。
- 评估缓存目录是否膨胀触发上限，必要时调整 key 粒度或分目录缓存。
du -sh ~/.cache /tmp/.buildx-cache 2>/dev/null
sha256sum pnpm-lock.yaml | head -c 64Commands
排查命令与使用意图
命令 1
用于补充“CI 缓存失效排查方法”的排查证据链。gh 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
gh cache list -R owner/repo --limit 30命令 2
用于补充“CI 缓存失效排查方法”的排查证据链。gh 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
gh cache delete <cache-key> -R owner/repo命令 3
用于补充“CI 缓存失效排查方法”的排查证据链。du 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
du -sh ~/.cache /tmp/.buildx-cache 2>/dev/null命令 4
用于读取日志或配置文件内容。重点看时间戳附近的 ERROR、FATAL、refused、timeout 等关键词。
sha256sum pnpm-lock.yaml | head -c 64Risk Notes
容易踩坑的地方
- 不要在日志里打印 secrets 或 token，CI 日志常被长期留存，泄露后难以追溯。
- 不要用 latest tag 做缓存 key，会导致产物不可复现甚至复用错误缓存。
- 不要在流水线中执行不安全的 shell 命令或从不可信源下载脚本。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 CI 缓存失效 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- 把 secrets 和环境变量在流水线里显式声明，避免依赖运行时隐式注入导致不一致。
- 为关键 job 加超时上限，防止卡死占用 Runner 影响其他流水线执行。
- 缓存 key 统一用 lockfile hash，不要用 latest tag 或时间变量，确保缓存可复现。
- 在流水线中增加构建产物验证步骤，如类型检查、lint 和测试，尽早发现质量问题。
常见问题
缓存明明存在却不命中？
多为 key 不一致、restore-keys 顺序问题或运行器操作系统不同导致前缀不匹配，核对日志里的 key 和实际 key。
缓存 key 该怎么设计？
用操作系统加依赖锁文件 hash 作为主 key，restore-keys 用前缀兜底，避免把构建产物或时间戳算进 key。
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- CI 缓存未命中
- github actions cache not hitting
- CI 构建变慢 缓存失效
- 缓存 key 计算错误
- gh cache list 查看缓存
- github actions 缓存清理
- pnpm 缓存不命中 CI
- cache restore-keys 不生效
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。