GitHub Actions 缓存键怎样按依赖锁文件精确失效缓存怎样完成一个可复用的最小示例

把 package-lock.json 的内容哈希放进缓存键，并在最小示例中省略 restore-keys，就能让锁文件变化对应一个新主键。缓存的是 npm 下载数据，依赖安装仍交给 npm ci；不能因为缓存命中就跳过安装。

GitHub 官方地址：https://github.com/

下面以仓库根目录已有 package.json、package-lock.json 的 npm 项目为例。需要仓库写权限、可用的 GitHub Actions，以及允许所用 action 的仓库策略。图片均为原创操作说明图，其中状态只用于说明判读方式。

1. 在仓库中新建缓存工作流

打开目标仓库的 Code → Add file → Create new file，在文件名字段填写 .github/workflows/cache-demo.yml。先确认根目录能看到两个 npm 文件；单体项目不要把另一个子项目的锁文件拿来计算本项目的键。

成功状态是编辑页的路径指向 workflows 目录，并显示新的 yml 文件名。没有 Add file 时，先确认登录账号对仓库有写权限；受保护分支可改为新建分支并提交 Pull request。

2. 提交按锁文件取哈希的配置

在文件编辑区粘贴以下完整内容，再通过 Commit changes 保存到默认分支，或在合并请求通过后合入默认分支。本例选用 GitHub 官方仓库文档中的 action 主版本写法，组织要求固定提交 SHA 时应替换为相应已审核提交。

# 手动运行便于对比同一锁文件与修改后的锁文件
name: cache-demo
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  npm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: '24'
          # 本例显式管理缓存，避免与自动缓存重复
          package-manager-cache: false
      - name: Check lock file
        shell: bash
        run: |
          # 锁文件缺失时直接失败，避免哈希为空的缓存键
          test -f package-lock.json
      - name: Cache npm packages
        id: npm-cache
        uses: actions/cache@v5
        with:
          path: ~/.npm
          # 按系统、运行时和锁文件内容隔离缓存
          key: ${{ runner.os }}-node24-npm-${{ hashFiles('package-lock.json') }}
      - name: Install locked dependencies
        # 即使缓存命中，仍按锁文件重建依赖树
        run: npm ci

回到 Code 文件页，确认已保存的内容包含 path: ~/.npm 和锁文件 hash 表达式。不要用 node_modules 替代本例缓存目录，也不要同时打开 setup-node 自动 npm 缓存。当前官方 action 使用的运行时与项目 node-version 是两个概念；自托管 runner 还需满足相应 action 的运行要求。

这里的“失效”意味着不再请求旧哈希的主键，并非删除旧缓存。GitHub 的缓存查找还受分支和缓存版本约束，主键未命中时也可能按键前缀匹配；本例把哈希放在键的末尾、没有追加其他片段，并省略 restore-keys，以减少意外复用旧锁文件缓存的情况。

3. 从运行详情确认缓存键变化

进入 Actions → cache-demo → Run workflow，选择默认分支并运行。点开新运行记录，再点 npm → Cache npm packages 展开日志。首次成功运行后，再次用相同提交手动运行，查看是否出现对应键的恢复记录；缓存可能被清理或受作用域限制，因此第二次不承诺必然命中。

接着在本地正常更新一项依赖，提交更新后的 package.json 和 package-lock.json，再运行相同工作流。比较两次日志中的完整 key：哈希部分应随锁文件内容变化。不要只改文件修改时间，也不要通过删除锁文件制造变化。图中的 HASH-A/HASH-B 是占位示意，不是执行所得哈希。

把示例复制到其他仓库时改哪些地方

子项目位于 web 目录时，锁文件检查改为 web/package-lock.json，hashFiles 参数同步改成该路径，安装步骤设置 working-directory: web。缓存目录仍需与 npm 实际使用的 cache 目录一致。多个包管理器不要共用 npm 前缀；切换 Node 主版本时同时更新 node-version 和键中的运行时片段。

如果希望新锁文件仍利用旧下载数据，可以自行增加受限 restore-keys，但这会允许回退恢复，不能再把“主键未命中”等同于“完全不使用旧缓存”。无论哪种策略，安装必须执行，由锁文件确定最终依赖树。

配置不生效时怎样回退

先保留 npm ci，移除 Cache npm packages 步骤，即可回到不使用显式下载缓存的安装流程。缓存只能减少部分重复下载，不能解决锁文件与 package.json 不一致，也不保证构建时间一定缩短。需要手动处理条目时，在仓库 Actions 页的 Caches 管理入口查看相关 key；不要为了缓存失败而取消依赖安装。

官方缓存规则：https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching。Action 参数：https://github.com/actions/cache；Node 设置参数：https://github.com/actions/setup-node。