CI/CD / 系统课时
缓存没有命中怎么定位
缓存没有命中怎么定位
GitHub Actions 缓存持续 miss 时,问题通常不在“缓存服务坏了”,而在缓存键发生变化、路径没有实际内容、分支作用域不同,或依赖锁文件改变。排查时应同时观察 key 的生成依据和缓存步骤日志,避免盲目修改 key。
学习目标
- 能从缓存日志判断是首次创建还是异常未命中
- 能检查 key、缓存路径、分支作用域和锁文件变化
- 能设计稳定且会随依赖变化失效的缓存键
先把 key 和路径变成可观察信息
缓存排障第一步是确认本次运行到底使用了什么 key。对于 actions/cache,key 必须精确匹配才能直接命中;restore-keys 可以在精确匹配失败后寻找前缀匹配的缓存。
下面以 npm 下载缓存目录为例。hashFiles('**/package-lock.json') 会让锁文件内容变化反映到 key 中:
name: cache-check
on:
workflow_dispatch:
jobs:
check-cache:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Show npm cache path
run: npm config get cache
- name: Restore npm cache
id: npm-cache
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-npm-
- name: Report cache result
run: echo "cache-hit=${{ steps.npm-cache.outputs.cache-hit }}"首次使用新 key 时,预期结果类似:
/home/runner/.npm
cache-hit=false相同 key 已存在时,最后一行预期为:
cache-hit=true实际日志还会包含缓存恢复或保存信息,其细节可能随 Action 版本变化,因此判断时重点看 cache-hit 和最终使用的 key。
检查 key 为什么变化
如果每次运行都 miss,先检查 key 中是否混入每次都会变化的数据,例如运行编号、提交 SHA 或时间戳。这些值会让每次运行产生全新的 key,缓存自然无法复用。
锁文件哈希则是有意的变化来源。package-lock.json、pnpm-lock.yaml、yarn.lock 等发生变化后,新 key miss 通常是正确行为,因为依赖集合已经改变。此时 restore-keys 可以复用较接近的旧缓存,再由包管理器补齐差异。
确认缓存路径真的有内容
key 正确并不意味着一定能保存有效缓存。路径写错、目录尚未创建,或者缓存步骤执行后没有任何工具向该目录写入内容,都会让后续运行无内容可恢复。
对于 npm,可用下面的命令确认真实缓存目录:
npm config get cache预期输出
/home/runner/.npmLinux GitHub-hosted runner 上通常得到上述路径;不同 runner 或配置下实际路径可能不同。应以命令返回值为准,并让 path 与真实缓存目录一致。
检查分支作用域和锁文件
缓存具有作用域限制,并不是仓库中任意分支创建的缓存都能被所有其他分支无条件读取。若默认分支可以命中,而某个功能分支持续 miss,应结合缓存创建分支、当前分支以及工作流触发方式检查可访问范围。

定位时不要把“锁文件变化导致新 key”和“缓存机制异常”混为一谈。最可靠的验证方法是在依赖和 key 都不变的前提下连续运行两次:第一次允许创建缓存,第二次应观察到精确命中;若仍为 false,再回到路径、保存日志和分支作用域继续检查。