GitHub Actions 缓存依赖并控制失效边界

GitHub Actions 依赖缓存的最小可用方案，是缓存包管理器的下载目录，把操作系统、CPU 架构、手动版本前缀和锁文件哈希放进 key。锁文件变化会自动生成新缓存；需要立即让整批缓存失效时，只改版本前缀。缓存命中后仍然执行 npm ci，这样依赖安装结果继续由 package-lock.json 决定，而不是把旧的 node_modules 当成事实来源。

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

最终结果应该是什么样

完成后，工作流应有三个可验收结果：

• 同一运行环境且 package-lock.json 未变化时，缓存步骤出现精确命中。
• 锁文件变化时，精确 key 未命中，但可以按需要从较宽的 restore-keys 恢复下载缓存。
• 把 npm-v2 改为 npm-v3 后，旧缓存不会继续作为精确结果使用。

本文缓存的是 ~/.npm 下载目录，不是 node_modules。前者适合作为可复用的下载加速层，后者容易受到 Node.js 版本、平台、本地二进制模块和安装脚本影响，失效维度更难完整表达。

步骤一：在仓库创建工作流文件

进入目标仓库后，依次选择 Code → Add file → Create new file。在文件名输入框填写 .github/workflows/cache-npm.yml。页面应显示仓库文件编辑器，路径栏完整出现 .github/workflows/，这是继续操作的确认状态。

把下面配置粘贴到编辑区。示例使用 actions/cache@v4，并将 runner.os、runner.arch、手动版本 npm-v2 和锁文件哈希组合为 key：

name: Node dependency cache

# 推送和拉取请求都执行，便于比较不同分支的缓存范围。
on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '20'

      - name: Cache npm downloads
        id: cache-npm
        uses: actions/cache@v4
        with:
          # 缓存 npm 下载目录，安装结果仍由 package-lock.json 决定。
          path: ~/.npm
          key: ${{ runner.os }}-${{ runner.arch }}-npm-v2-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-${{ runner.arch }}-npm-v2-

      - name: Install dependencies
        run: npm ci

      - name: Report cache result
        shell: bash
        run: |
          # true 表示精确 key 命中；其他值需要结合缓存步骤日志判断。
          echo "cache-hit=${{ steps.cache-npm.outputs.cache-hit }}"

      - name: Run tests
        run: npm test

在编辑页右上角选择 Commit changes...，填写提交说明后确认提交。此时 GitHub 会根据 push 触发工作流。若仓库规则要求走分支和拉取请求，则选择创建新分支，再按团队规则合并。

步骤二：理解 key 与失效边界

actions/cache 的缓存由 key、缓存版本和分支范围共同决定。示例 key 的四段分别承担不同边界：

GitHub Actions 的既有缓存内容不能原地修改。精确 key 未命中且任务成功完成时，新的缓存会以新 key 保存。这个特性意味着“失效”应通过新 key 表达，而不是期待覆盖旧缓存。

restore-keys 是按顺序匹配的前缀。示例只保留同操作系统、同架构、同人工版本的前缀，避免跨平台或跨缓存结构恢复。恢复到旧锁文件对应的 npm 下载缓存通常仍可接受，因为随后执行的 npm ci 会按当前锁文件校正依赖；如果缓存的是编译产物，则不能使用这么宽的恢复前缀。

步骤三：运行工作流并核对缓存状态

进入仓库后依次打开 Actions → Node dependency cache → 最新运行 → test。在步骤列表中展开 Cache npm downloads，然后查看 Report cache result。

建议连续触发两次未改锁文件的运行：

1. 第一次通常是缓存未命中，任务成功后创建缓存。
2. 第二次使用同一精确 key，应看到 cache-hit=true。
3. 修改并提交 package-lock.json 后，精确 key 应变化；若命中 restore-keys 前缀，cache-hit 不会等同于精确命中。

不要仅凭工作流总耗时判断缓存有效。网络、runner 冷启动和测试时长都会波动。可靠证据是缓存步骤日志、实际 key、cache-hit 输出以及后续 npm ci 是否成功。

步骤四：在 Caches 页面核对和删除

进入仓库后选择 Actions，在左侧 Management 区域点击 Caches。列表会显示缓存 key、分支、大小、创建时间和最后使用时间。使用顶部 Filter caches 输入 key:Linux-X64-npm-v2-，可以集中查看当前版本前缀下的缓存。

有仓库写权限的用户可以点击目标缓存右侧的删除图标。手工删除适合处理异常缓存或释放空间；日常依赖变化优先依靠锁文件哈希生成新 key。删除后重新运行工作流，应看到一次未命中并在成功结束后重新创建缓存。

缓存存在分支范围限制。运行通常可以恢复当前分支或默认分支可见的缓存；拉取请求创建的缓存可能限制在对应的合并引用范围。看到“同一个 key 却没命中”时，先比较分支、缓存版本和 path，而不是反复重跑。

中间状态怎么判断

缓存动作会在精确未命中且任务成功结束后保存 path。如果测试提前失败，或 ~/.npm 没有产生可保存内容，就不会得到预期的新缓存。缓存不是构建产物归档；需要长期下载的安装包、测试报告或发行文件应使用 artifact 或发布资产。

异常修正

锁文件变了，依赖仍像旧版本

先确认缓存的是 ~/.npm，并且安装命令使用 npm ci。如果缓存了 node_modules，旧目录可能掩盖真实安装过程。把 path 改回包管理器下载目录，同时把人工版本从 npm-v2 提升为 npm-v3。

每次都创建新缓存

检查 key 中是否包含提交 SHA、运行编号或其他每次都变化的值。依赖缓存通常只需要平台、架构、工具版本和锁文件哈希。过度细分会快速消耗仓库缓存空间并产生缓存震荡。

恢复到了不兼容的旧缓存

缩窄 restore-keys，把 Node.js 主版本、包管理器主版本或构建参数纳入 key。恢复前缀越宽，命中率可能越高，但校验成本和不兼容风险也越高。

缓存存在但当前分支找不到

在 Caches 页面检查缓存的分支范围。默认分支缓存通常可供其他分支恢复，但特定分支和拉取请求缓存受范围限制。不要通过把敏感文件放入缓存来绕开范围；官方明确不建议缓存令牌、凭据等敏感信息。

仓库缓存不断被淘汰

GitHub 会依据仓库缓存存储和保留规则清理条目。先在 Caches 页面按大小和最后使用时间排查，再删除高频生成且收益低的缓存，减少 key 维度，或由仓库管理员评估缓存设置。不要把缓存当作长期存档。

归档记录

每次调整缓存策略，建议在拉取请求中记录以下信息：缓存 path、key 模板、人工版本号、restore-keys 范围、首次未命中的运行链接、第二次精确命中的运行链接，以及 Caches 页面中对应条目的 key。这样后续升级 Node.js、切换包管理器或修改目录结构时，可以明确判断应该增加新维度，还是只提升人工版本。

相关问题

能不能命中后跳过 npm ci？

缓存 ~/.npm 时不能跳过。它只保存下载缓存，项目依赖仍需由 npm ci 按锁文件安装。

什么时候应该改 npm-v2？

当缓存 path、缓存内容结构、包管理器策略或兼容维度发生变化时提升版本；普通依赖升级由锁文件哈希自动处理。

为什么不直接缓存 node_modules？

node_modules 可能包含平台、架构和 Node.js ABI 相关内容，安装脚本也可能依赖当前环境。缓存 npm 下载目录通常更稳健，代价是每次仍要执行安装。