GitHub Actions 怎样缓存依赖并避免键冲突

在 GitHub Actions 中缓存依赖，应先确定缓存目录，再让 key 区分项目、系统、架构、运行时和锁文件。不要只写一个 npm-cache 通用键，也不要用过宽的 restore-keys 把不兼容环境重新混在一起。本文缓存 npm 下载包，安装依赖仍执行 npm ci。

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

缓存文档：https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching；Action 官方仓库：https://github.com/actions/cache。配图是原创界面说明图，不是实际仓库截图或运行证明。

任务目标：缓存下载包，安装仍按锁文件执行

用一个原创示例仓库 catalog-web 说明：根目录已有 package.json、package-lock.json 和 build 脚本，GitHub Actions 已启用，操作者有提交工作流的权限。目标是减少重复下载，不承诺每次都命中，更不把缓存当成发布产物存储。

这里显式使用 .ci-cache/npm 作为下载缓存目录，便于 key 与 path 一起维护。示例选 GitHub 托管 Ubuntu 环境、Node 24；其他环境应按项目支持范围调整。Action 自身运行环境与被安装的 Node 版本是两回事，自托管 runner 要另行满足所用 Action 的运行要求。

步骤一：在仓库中打开工作流文件

进入目标仓库“Code → Add file → Create new file”，文件名填写 .github/workflows/dependency-cache.yml。已有工作流时，则在 Code 文件树中打开该文件并点击编辑入口，把缓存逻辑合并到原有构建 job，避免新增一条重复构建流程。

继续前确认文件编辑区域已出现，名称包含 .github/workflows 和 .yml。扩展名或目录拼错时，普通文件虽然能保存，也不会因此成为预期工作流。

步骤二：保存带命名空间的缓存配置

在文件内容区域填入下面的 YAML。它是供读者使用的完整示例，本文没有替任何仓库提交或运行。cache 的 key 与回退前缀都保留同一组隔离维度，只放宽最后的锁文件摘要。

name: Dependency cache build

# 默认分支上的手动入口，便于观察连续两次相同输入
on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ['24']
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          # 只保留下面这一套显式缓存，避免重复管理同一路径
          package-manager-cache: false

      - name: Check lockfile
        shell: bash
        run: |
          # 防止锁文件路径写错后，多种依赖集合共用空摘要
          test -f package-lock.json

      - name: Restore npm downloads
        id: npm-downloads
        uses: actions/cache@v6
        with:
          path: .ci-cache/npm
          key: catalog-web-npm-v1-${{ runner.os }}-${{ runner.arch }}-node${{ matrix.node }}-${{ hashFiles('package-lock.json') }}
          restore-keys: |
            catalog-web-npm-v1-${{ runner.os }}-${{ runner.arch }}-node${{ matrix.node }}-

      - name: Install locked dependencies
        shell: bash
        run: |
          # 命中下载缓存也照常安装；缓存不等于 node_modules
          npm ci --cache "$GITHUB_WORKSPACE/.ci-cache/npm" --prefer-offline

      - name: Build project
        run: |
          # 使用项目已有构建脚本，失败应按真实日志处理
          npm run build

key 的 catalog-web-npm-v1 是项目、包管理器和缓存规则版本的命名空间。系统与架构隔离运行环境，Node 维度区分项目选择，hashFiles 绑定当前锁文件。它们解决的是人为漏写维度造成的复用混淆，而不是宣称数学上绝无哈希碰撞。缓存还有服务端作用域及版本机制，key 不是唯一约束。

完成编辑后点击“Commit changes”，按仓库规则选择提交到默认分支，或先创建分支与 Pull Request 合并。界面应显示新提交及保存后的工作流文件。手动工作流入口要求工作流文件位于默认分支，未合并的文件不要直接当作已生效。

步骤三：在 Actions 查看命中与安装状态

进入“Actions → Dependency cache build → Run workflow”，选择分支并点击 Run workflow。待运行记录出现后打开该记录，再进入 build job，展开 Restore npm downloads、Install locked dependencies 和 Build project 三个步骤。

第一次没有匹配缓存是正常情况。使用组合 cache Action 时，未精确命中会在 job 成功完成后尝试保存当前 key；再次用相同输入运行，才有机会看到精确命中。缓存可能被清理、受作用域限制或没有成功保存，所以第二次仍需根据真实日志判断。

精确命中对应 cache-hit 的字符串 true；回退命中不应按精确命中处理。本文无论如何都安装依赖，因为缓存目录只是下载包。即使缓存里保留旧下载文件，npm ci 仍应根据锁文件安装目标依赖；不要给安装步骤加“命中就跳过”的条件。

常见问题与验收要点

相同 key 能覆盖旧缓存吗？

已有缓存内容不能原地修改。缓存规则或内容范围变更时，用新 key。并发保存时不要把“另一个 job 已先保存”误判为构建本身失败，应分别查看缓存步骤与业务步骤状态。

必须设置 restore-keys 吗？

不是。不希望复用旧锁文件下载缓存时可以移除，让命中条件更窄。回退只应服务于明确可兼容的数据，不能照搬到编译产物或带本机原生模块的安装目录。

为什么 key 一样却读不到缓存？

继续检查分支作用域、缓存路径、压缩相关版本及清理情况。不要通过放宽到一个全局前缀来掩盖原因。缓存中也不要存凭据、令牌和个人数据。

验收时分别确认三个事实：工作流已保存到正确位置，日志显示实际使用的缓存键与目录，安装和构建完成了各自的工作。缓存命中只反映复用情况，不能替代业务构建结果。