GitHub Actions 缓存键变化后为什么仍复用旧缓存

GitHub Actions 的缓存键改了，却仍然拿到旧依赖，最常见的原因不是 GitHub 忽略了新 key，而是缓存动作在精确匹配失败后继续做了前缀匹配，或者从当前分支回退到了默认分支。先看日志里的“实际恢复键”和 cache-hit，再决定是否要删缓存。

官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching

只要缓存键的前缀部分符合当前分支的缓存查找规则，就算自定义的后缀发生变化，只要此前存在过符合前缀规则的旧缓存，GitHub Actions 还是会优先命中可部分匹配的历史缓存。

第一步：先把真正参与匹配的 key 看清楚

进入“仓库 → .github/workflows/ → 对应工作流文件 → 编辑”，找到缓存步骤。把依赖文件哈希和运行环境写进主键，避免只改了注释或无关字段却以为缓存已切换。

- name: Cache npm
  id: npm-cache
  uses: actions/cache@v4
  with:
    path: ~/.npm
    # 用系统、任务名和锁文件哈希区分可复用内容
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    # 只保留同一任务的较窄前缀，避免跨任务拿到旧目录
    restore-keys: |
      ${{ runner.os }}-npm-

例如锁文件哈希从 abc123 变成 def456 后，主键确实变成了 ubuntu-npm-def456。但如果没有这个精确项，ubuntu-npm- 仍能匹配最近创建的旧缓存，所以“看起来复用旧缓存”是预期的回退行为。

第二步：在 Actions 日志中区分三种命中结果

打开“仓库 → Actions → 运行记录 → 具体工作流 → 具体 job”，展开缓存步骤。先看 cache-hit 输出，再看日志是否出现主键、前缀或 restored key。不要只根据“Cache restored”一句话判断是新缓存。

如果只是依赖文件改变，主键应当变化；如果日志仍显示旧内容，重点查是否命中了 restore-keys。缓存动作不能修改已有条目，新的主键会产生新的条目，旧条目仍会保留到被清理。

第三步：检查分支作用域与 pull request 场景

GitHub Actions 不是把所有缓存放在一个无边界的公共池里。缓存搜索首先受当前工作流引用和分支作用域限制；当前分支没有匹配时，规则允许再搜索默认分支。子分支、兄弟分支和不同 tag 并不能任意互相恢复缓存。

因此，feature 分支改了锁文件后仍恢复旧缓存，可能是两层因素叠加：当前分支没有新 key，于是通过宽泛前缀找到了旧项；或者当前分支无结果后，从默认分支找到同名前缀。若是 pull request，缓存可能属于 merge ref，只能由同一 PR 的重跑使用。

第四步：把回退策略改成可解释的配置

排障时可暂时删除 restore-keys，观察依赖改变后是否真正 miss；确认主键设计无误后，再加回最窄的前缀。建议把操作系统、包管理器和锁文件哈希放入主 key，把任务名作为前缀，避免 npm、构建产物和测试目录共享同一条恢复路径。

还要检查“仓库 → Settings → Actions → General”中的缓存相关设置，以及 workflow 是否由可信触发器运行。缓存内容不应放入 token、登录凭据等敏感文件；恢复到工作区的内容应当按不可信输入对待。

常见问题

改了 key 后旧缓存会被覆盖吗？

不会。已有缓存内容不能原地修改，新的 key 会创建新条目；旧条目由 GitHub 的缓存清理和保留策略处理。

为什么 cache-hit 是 false 却有依赖文件？

这通常表示没有精确命中主 key，但通过前缀或 restore-keys 恢复了一个近似缓存。它能加速安装，不等于依赖版本已经完全匹配。

删掉 restore-keys 就一定不会复用默认分支吗？

不能这样绝对判断。它会去掉前缀回退，但分支作用域和默认分支搜索仍由 GitHub Actions 的缓存规则决定；应以本次运行日志和实际 key 为准。