GitHub Actions中Yarn缓存未找到问题求助

问题描述 #

我的GitHub Actions配置如下：

runs-on: ubuntu-latest
steps:
  - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
  - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
    with:
      node-version: 20
      cache: yarn
      cache-dependency-path: "yarn.lock"
  - run: yarn install --immutable

持续收到“yarn cache is not found”的提示，作业自动使用Yarn Classic而非yarn.lock指定的Yarn 4版本。

原因分析 #

1. 缓存机制不兼容：Yarn 4（Berry）的缓存结构、路径和标识逻辑和Yarn Classic完全不同，actions/setup-node的cache: yarn选项是为Yarn Classic设计的，无法识别Yarn 4的缓存目录，因此会提示缓存未找到。
2. 依赖配置文件不全：Yarn 4的版本和缓存规则由.yarnrc.yml管理，仅指定yarn.lock作为缓存依赖路径，无法生成匹配Yarn 4的缓存键，导致缓存无法命中。
3. Corepack未正确配置：Yarn 4通过Corepack分发，若环境未启用Corepack或未指定Yarn版本，缓存缺失时会自动 fallback 到默认的Yarn Classic。

解决方法 #

修改GitHub Actions配置，适配Yarn 4的缓存和版本管理需求：

runs-on: ubuntu-latest
steps:
  - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
  - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
    with:
      node-version: 20
  # 启用Corepack并设置Yarn版本（从yarn.lock或.yarnrc.yml读取）
  - name: Setup Yarn 4
    run: |
      corepack enable yarn
      yarn set version from sources
  # 手动配置Yarn 4的缓存规则
  - name: Cache Yarn 4 dependencies
    uses: actions/cache@v3
    with:
      path: |
        .yarn/cache
        .yarn/unplugged
        .yarn/build-state.yml
        .pnp.*
        .yarn/releases # 若仓库包含Yarn二进制文件，加入此路径
      key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock', '.yarnrc.yml') }}
      restore-keys: |
        ${{ runner.os }}-yarn4-
  - run: yarn install --immutable

配置说明 #

• Corepack启用：通过corepack enable yarn开启Yarn的版本管理，确保环境使用yarn.lock或.yarnrc.yml指定的Yarn版本。
• 自定义缓存路径：明确指定Yarn 4的缓存目录和依赖文件，覆盖actions/setup-node的默认缓存逻辑。
• 精准缓存键：结合yarn.lock和.yarnrc.yml的哈希值生成缓存键，保证缓存匹配的准确性，避免不必要的缓存失效。

内容的提问来源于stack exchange，提问作者DJ123dd