GitHub Actions 缓存键怎样避免依赖串用

GitHub Actions 依赖缓存出现“串用”，通常不是 npm 或构建工具突然读错了文件，而是缓存键把本来不同的依赖集合归到了同一个前缀。最稳妥的做法是让精确键包含运行系统、包管理器和锁文件哈希；如果确实需要分支隔离，再加入分支名。restore-keys 也不能写成过于宽泛的 npm-，否则缓存未精确命中时，最近创建的另一套依赖可能被恢复。

官方地址：https://github.com/actions/cache

缓存参考文档：https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching

下面以 npm 的 package-lock.json 为例。文中的界面都是 ImageGen 生成的原创操作说明图，不是 GitHub 实际截图，也不代表已经在某个仓库运行过。

1. 先分清是精确命中还是前缀回退

先打开仓库的 Actions 页面，选择一个工作流运行记录，再查看使用缓存的 job 日志。重点看三种状态：完整 key 找到同名条目是 exact hit；完整键没有命中但某个前缀找到了条目，是 prefix restore；两者都找不到，job 成功后才会按本次完整键保存新缓存。第三种不是错误，第一次改变锁文件时本来就可能发生。

如果日志显示“恢复成功”，但后续安装仍然出现不属于当前分支的依赖，先不要删缓存。回到 workflow 文件，检查 key 是否缺少锁文件哈希，以及 restore-keys 是否退得太宽。缓存搜索会按精确键、键的前缀和 restore keys 的顺序查找；一个宽前缀下有多个匹配时，可能取最近创建的那个。

2. 在 workflow 中组合不会混用的 key

进入仓库的 Code 标签，打开 .github/workflows/ 下实际执行安装步骤的 YAML 文件，点击编辑按钮。找到 actions/cache 或包管理器 setup action 的缓存配置，把原来只有 npm-、固定版本或固定字符串的键替换为包含锁文件哈希的写法。

steps:
  - name: Use Node.js
    uses: actions/setup-node@v4
    with:
      node-version: 20

  - name: Cache npm dependencies
    uses: actions/cache@v4
    with:
      path: ~/.npm
      # 系统、包管理器和锁文件内容共同决定一套依赖
      key: ${{ runner.os }}-node20-npm-${{ hashFiles('**/package-lock.json') }}
      # 回退时仍保留锁文件哈希，不能退成裸的npm前缀
      restore-keys: |
        ${{ runner.os }}-node20-npm-${{ hashFiles('**/package-lock.json') }}-

  - name: Install dependencies
    run: npm ci # npm ci按锁文件安装，避免把package.json与锁文件悄悄合并

这里的 hashFiles('**/package-lock.json') 让锁文件内容变化时生成新的 key。runner.os 防止 Linux 和 Windows 共用同一条缓存；node20 是示例中的运行时边界，换 Node 主版本时也会自然分开。若仓库使用 pnpm 或 Yarn，应将包管理器名称、锁文件和缓存路径一起替换，不能只改字符串。

如果依赖本身必须按分支独立，例如分支会生成不同的私有构建产物，可把 ${{ github.ref_name }} 加入精确 key：

key: ${{ runner.os }}-node20-${{ github.ref_name }}-npm-${{ hashFiles('**/package-lock.json') }}
# 只在同一分支和同一锁文件内回退
restore-keys: |
  ${{ runner.os }}-node20-${{ github.ref_name }}-npm-${{ hashFiles('**/package-lock.json') }}-

分支名不是所有依赖缓存都必须加入的字段。GitHub 本身会按分支作用域查找缓存，并在找不到时按文档规则尝试默认分支；加入分支名会牺牲跨分支复用，换来更明确的隔离。对于只存包管理器下载内容的缓存，锁文件哈希通常是更关键的隔离条件。

3. 把 restore-keys 收窄到可接受的范围

在同一个 with 配置里，沿着 key → restore-keys 检查每一层前缀。安全的原则是：前缀可以省略“本次运行的细节”，但不要省略会改变依赖集合的字段。比如保留锁文件哈希，比直接回退到 ${{ runner.os }}-npm- 更安全；后者可能在多次 lockfile 变更后恢复另一组依赖。

保存文件后，点击工作流页面的 Run workflow（如果仓库允许手动运行），或提交一次只修改 workflow 的分支。第一次新键出现 miss 是预期现象；真正需要关注的是新运行是否保存了带新哈希的条目，以及安装步骤是否继续使用当前锁文件。

4. 从缓存列表核对是否还会串用

进入仓库 Actions → Caches，在 Filter caches 输入一个足够具体的前缀，例如 key: linux-node20-npm-。逐条查看 key、分支和创建时间。你应该能看到不同 lockfile hash 对应不同条目；如果只看到一个固定键，说明 workflow 仍然没有把锁文件纳入 key。

若列表中存在旧的宽键，不要仅凭它仍然存在就判断新配置失败。先让新 workflow 至少成功保存一条新键，再按仓库权限从缓存条目右侧的删除入口清理旧条目，或者使用 GitHub CLI 管理缓存。清理的目标应是具体旧 key，不要把整仓库缓存全部删除来“碰运气”。

# 只列出当前仓库可见的缓存，先确认旧键的完整名称
gh cache list --limit 100

# 按完整 key 删除已确认的旧条目；替换为你自己的旧键
gh cache delete 'linux-node20-npm-fixed' --confirm

gh cache 只用于管理缓存条目，不会替你修正 workflow 的 key 设计。若删除后问题再次出现，回到 YAML 检查是否仍有另一个 job 使用固定键，或者是否有多个 workflow 共用同一缓存路径却没有共享相同的锁文件边界。

5. 常见误区与回退方案

为什么依赖更新后仍然显示 cache hit？通常是提交没有改变被 hashFiles 匹配的锁文件，或者旧配置仍在执行。确认 workflow 运行的分支、文件路径和匹配模式；不要用“重新运行”代替检查 key。

为什么加了 restore-keys 反而更容易串用？因为 restore key 是前缀搜索，不是等值比较。多个部分匹配时会按规则选择最近创建的缓存，所以前缀越短，允许混用的集合越大。依赖缓存宁可 miss 后重新下载，也不要恢复无法解释的旧集合。

能不能把构建产物也放进这个 key？不要把缓存和 artifact 混为一谈。缓存适合可重新生成的依赖或中间文件；构建产物、日志和需要在 job 之间传递的结果应使用 artifact。两者的生命周期和读取语义不同。

最后保留一份可读的 key 约定：先写运行系统，再写运行时或包管理器，再写锁文件哈希，最后才决定是否加分支；restore-keys 只保留仍能证明依赖相同的前缀。这样即使缓存被淘汰，job 也能重新下载依赖，依赖串用不会靠一次“清空缓存”暂时掩盖。