コンテンツへスキップ

GitHub ActionsでYarnの依存関係をキャッシュする

最終更新

GitHub Actions で Yarn をキャッシュするには、actions/setup-node に cache: yarn を設定し、ロックファイルを固定してインストールします。注意点として、Yarn Classic(1.x)と Yarn Berry(2 以降)ではパッケージの保存場所とフラグが異なるため、手順もそれぞれ異なります。

まず使用しているバージョンを確認します。yarn --versionを実行すると、Classicでは1.22.x、Berryでは3.xまたは4.xと表示されます。

オプション1:setup-nodeの組み込みキャッシュ

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: corepack enable          # needed for Berry and packageManager pinning
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: yarn
      - run: yarn install --immutable   # Berry
      # Classic: yarn install --frozen-lockfile
      - run: yarn test

setup-nodeのREADME(2026年10月確認)によると、cache: yarnはデフォルトでyarn.lockをハッシュ化し、パッケージマネージャーがすでにインストールされている必要があります。setup-nodeの前にcorepack enableを実行すると、package.json内のpackageManagerに記載されたYarnのバージョンが利用可能になります。複数のロックファイルを使用する場合はcache-dependency-pathを使用してください。

オプション2: Classic向けの明示的なactions/cache

Classicはグローバルキャッシュを保持します。その場所を次のコマンドで確認します。

- uses: actions/setup-node@v7
  with:
    node-version: 22
- name: Get Yarn cache dir
  id: yarn-cache
  run: echo "dir=$(yarn cache dir)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.yarn-cache.outputs.dir }}
    key: yarn-classic-${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
    restore-keys: |
      yarn-classic-${{ runner.os }}-
- run: yarn install --frozen-lockfile

オプション3: Berry向けの明示的なactions/cache

Berry のキャッシュの場所は、.yarnrc.yml の enableGlobalCache の設定によって変わります。推測せず、実際の設定を確認してください:

- run: corepack enable
- uses: actions/setup-node@v7
  with:
    node-version: 22
- name: Get Yarn cache folder
  id: yarn-cache
  run: echo "dir=$(yarn config get cacheFolder)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.yarn-cache.outputs.dir }}
    key: yarn-berry-${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
    restore-keys: |
      yarn-berry-${{ runner.os }}-
- run: yarn install --immutable

リポジトリでnodeLinker: node-modulesを使用している場合も、インストールはこのキャッシュフォルダから読み込み、その後node_modulesを書き込みます。Plug'n'Play (既定)を使用している場合はnode_modulesが存在せず、Yarnは.pnp.cjsを書き込み、zipアーカイブを直接読み込みます。

Berryに関する注意点

  • ゼロインストール。検証用の.yarn/cacheをgitにコミットしている場合、チェックアウトの時点でパッケージが揃っています。キャッシュするものはないため、キャッシュステップを追加すると余計な負荷になるだけです。ただし、リポジトリのサイズが大きくなるという トレードオフがあります。
  • immutableインストール。yarn install --immutableは、ロックファイルが変更される場合に失敗します。CIではこの動作が望ましいです。Berryには、キャッシュが変更される場合に失敗させる--immutable-cacheもあります。
  • キャッシュキー。runner.osを含めてください。ネイティブバインディングを持つパッケージの場合、Berryのキャッシュアーカイブにはプラットフォーム固有のビルドが含まれることがあります。

node_modulesをキャッシュしない理由

npmガイドと同じ理由です。新しいインストールで書き換えられ、ある Node.jsバージョン向けにビルドされたネイティブモジュールは別のバージョンで動作しなくなります。パッケージキャッシュは再利用しても安全で、復元にかかるコストも低い部分です。

セットアップキャッシュ対象インストールコマンド
Classic 1.xyarn cache diryarn install --frozen-lockfile
Berry、グローバルキャッシュyarn config get cacheFolderyarn install --immutable
Berry、ゼロインストールなし (コミット済み)yarn install --immutable --immutable-cache

キャッシュヒットの確認方法

  1. 復元ステップのログには、ヒット時にCache restored from key: ...、ミス時にCache not found for input keys: ...と表示されます。
  2. Berryの場合、インストール出力には解決、取得、リンクの各ステップと所要時間が表示されます。キャッシュが温まっていると取得ステップはほぼ一瞬で終わり、冷えている場合はダウンロード中のパッケージが一覧表示されます。
  3. Classicの場合、キャッシュが温まっているインストールはリンク段階が大半を占め、取得段階は短くなります。
  4. gh cache list --key yarn- --limit 20を実行すると、保存された内容と最終使用日時を確認できます。

よくある間違い

  1. 誤ったファイルのハッシュ化。package.jsonはyarn.lockよりも頻繁に変更され、不必要にキャッシュを無効化します。ロックファイルをハッシュ化してください。
  2. Corepackを有効にしていない。setup-nodeのキャッシュステップはyarnを実行します。誤ったグローバルのYarnが応答すると、報告されるキャッシュディレクトリも誤ったものになります。
  3. ClassicとBerryで同じキーを使用。移行する場合は、古いレイアウトが復元されないようにキーのプレフィックスを変更してください。
  4. PRでのみキャッシュ。ブランチ単位のスコープでは、PRのキャッシュは共有されません。mainでも実行してください。詳しくはGitHub Actionsのキャッシュを参照してください。
  5. サイズの無視。Berryのキャッシュにはzipアーカイブが含まれ、大規模なモノレポでは数GBに達することがあります。10 GBの上限に注意してください。

よくある質問

setup-nodeはYarn Berryのキャッシュに対応していますか?

はい、cache: yarnで対応しています。セットアップステップの前にCorepackが正しいYarnのバージョンを有効にしていることを確認してください。

.yarn/cache (ゼロインストール)はコミットすべきですか?

キャッシュステップとパッケージのインストールにかかるネットワーク時間を省けますが、リポジトリのサイズが大きくなり、差分も見づらくなります。これはCI上の要件ではなく、チームの好みによる判断です。

CIで yarn install --immutable が失敗するのはなぜですか?

ブランチ上のロックファイルが package.json と一致していません。ローカルで yarn install を実行し、yarn.lock をコミットしてください。

モノレポではYarnのキャッシュは異なりますか?

ワークスペースは1つのロックファイルと1つのキャッシュフォルダーを共有するため、設定方法は同じです。ロックファイルが複数ある場合は cache-dependency-path を使用してください。

次のステップ

pnpm と npm の場合についても確認でき、キャッシュの後に試せる方法は GitHub Actionsを高速化する方法 で紹介しています。キャッシュヒット率の向上によってどれだけ節約できるかは、キャッシュ節約額の見積もりツールで確認できます。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す