2.1 Pnpm Store 缓存策略#

pnpm 使用内容寻址存储（Content-addressable store）。我们应该缓存 pnpm 的全局 store 目录，而不是每个项目的 node_modules。这样即使多个项目共享同一个 Runner，也能实现最大化的复用。

1
- name: Install pnpm
2
  uses: pnpm/action-setup@v3
3
  with:
4
    version: 9
5

6
- name: Get pnpm store directory
7
  shell: bash
8
  run: |
9
    echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
10

11
- name: Setup pnpm cache
12
  uses: actions/cache@v4
13
  with:
14
    path: ${{ env.STORE_PATH }}
15
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
16
    restore-keys: |
17
      ${{ runner.os }}-pnpm-store-

2.2 为什么使用 hashFiles？#

hashFiles('**/pnpm-lock.yaml') 会根据锁文件的内容生成唯一的哈希值。只要依赖版本没有变动，哈希值就保持不变，从而精准命中缓存。一旦开发者更新了某个包，哈希值改变，CI 会重新安装并更新缓存。

3.1 Turborepo 远程缓存模拟#

Turborepo 默认支持将构建结果缓存到 .turbo 目录。在 GitHub Actions 中，我们可以持久化这个目录。

1
- name: Cache Turborepo
2
  uses: actions/cache@v4
3
  with:
4
    path: .turbo
5
    # 使用 github.sha 确保每次提交都有机会更新缓存
6
    # 但通过 restore-keys 继承上一次的产物
7
    key: ${{ runner.os }}-turbo-${{ github.sha }}
8
    restore-keys: |
9
      ${{ runner.os }}-turbo-
10

11
- name: Build
12
  run: pnpm build --cache-dir=".turbo"

3.2 缓存命中流转图#

通过合理的配置，CI 的执行路径如下：

graph TD
    Start[开始 CI 运行] --> CheckCache{检查 Cache Key}
    CheckCache -->|Hit 精确命中| Restore["恢复目录内容"]
    CheckCache -->|Miss 未命中| RestorePartial["尝试 Restore-keys 模糊恢复"]
    Restore --> Install["执行 pnpm install --frozen-lockfile"]
    RestorePartial --> Install
    Install --> Build["执行 pnpm build"]
    Build --> SaveCache[上传新缓存]
    SaveCache --> End[结束]
    
    subgraph Optimization
        Install -.->|依赖缓存命中| Build
    end

4.1 缓存污染的元凶#

当我们在用 actions/cache 缓存 Webpack 或 Vite 的 .cache 目录时，构建工具每次都会在里面生成带有新 Hash 的中间产物（比如 vendor.a1b2.js.cache）。 GitHub Actions 的 save 动作是累加的：它会把当前目录的所有内容打包传上去。这意味着：旧的、再也不会用到的文件（比如上个月的旧 Hash 产物），会一直躺在这个缓存包里，跟着你的项目不断滚雪球。

最终，光是下载和解压这个庞大的垃圾缓存包，耗时就超过了重新构建一遍的时间！

工业级解决方案：预清理 (Pre-clean) 与强一致性哈希

在打包结束后、缓存保存前，我们必须执行一个清理脚本，或者利用构建工具自带的 prune 机制。 例如对于 next.js 的缓存，我们可以用 actions/cache 的官方高级插件 setup-node，它底层处理得更干净；或者手动删除那些 N 天前生成的旧文件：

1
- name: 🧹 Clean up old cache files before saving
2
  run: |
3
    # 在上传缓存前，删除 .turbo 或 node_modules/.cache 下超过 7 天未访问的文件
4
    find .turbo -type f -atime +7 -delete
5
    find node_modules/.cache -type f -atime +7 -delete

4.2 并发矩阵构建 (Matrix Strategy) 的包级缓存陷阱#

在 Monorepo 中，如果你为了加速，开了 4 台机器（Matrix）并行测试 4 个子包：

1
strategy:
2
  matrix:
3
    package: [web, admin, docs, ui]

如果每台机器都在最后一步执行了 actions/cache@v4 的 save 操作，去覆盖同一个 key: pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}。 由于并发执行，这 4 台机器会产生竞争条件 (Race Condition)，GitHub 会拒绝后 3 台机器的上传（Cache already exists），导致它们的局部构建缓存永远无法被保存。

破局思路：读写分离与后缀区分

对于并行任务，缓存的 key 必须包含机器的唯一标识，或者将“依赖安装”与“业务构建”分拆到两个独立的 Job 中（如：先由一个单独的 setup job 跑完 pnpm install 并上传 node_modules 缓存，后置的 4 个 Matrix job 全部只读（利用 restore-keys 命中））。

1
# 读写分离架构示例
2
jobs:
3
  setup-dependencies:
4
    runs-on: ubuntu-latest
5
    steps:
6
      # ... 安装依赖并强制存入精确 key 的缓存
7
      - uses: actions/cache/save@v4 # 注意这里用的是专门的 save action
8

9
  parallel-builds:
10
    needs: setup-dependencies
11
    strategy:
12
      matrix:
13
        app: [web, admin]
14
    steps:
15
      # ... 所有的并行节点，只负责 restore，绝不互相覆盖 save！
16
      - uses: actions/cache/restore@v4
17
        with:
18
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}