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.x | yarn cache dir | yarn install --frozen-lockfile |
| Berry、グローバルキャッシュ | yarn config get cacheFolder | yarn install --immutable |
| Berry、ゼロインストール | なし (コミット済み) | yarn install --immutable --immutable-cache |
キャッシュヒットの確認方法
- 復元ステップのログには、ヒット時に
Cache restored from key: ...、ミス時にCache not found for input keys: ...と表示されます。 - Berryの場合、インストール出力には解決、取得、リンクの各ステップと所要時間が表示されます。キャッシュが温まっていると取得ステップはほぼ一瞬で終わり、冷えている場合はダウンロード中のパッケージが一覧表示されます。
- Classicの場合、キャッシュが温まっているインストールはリンク段階が大半を占め、取得段階は短くなります。
gh cache list --key yarn- --limit 20を実行すると、保存された内容と最終使用日時を確認できます。
よくある間違い
- 誤ったファイルのハッシュ化。
package.jsonはyarn.lockよりも頻繁に変更され、不必要にキャッシュを無効化します。ロックファイルをハッシュ化してください。 - Corepackを有効にしていない。setup-nodeのキャッシュステップは
yarnを実行します。誤ったグローバルのYarnが応答すると、報告されるキャッシュディレクトリも誤ったものになります。 - ClassicとBerryで同じキーを使用。移行する場合は、古いレイアウトが復元されないようにキーのプレフィックスを変更してください。
- PRでのみキャッシュ。ブランチ単位のスコープでは、PRのキャッシュは共有されません。
mainでも実行してください。詳しくはGitHub Actionsのキャッシュを参照してください。 - サイズの無視。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を高速化する方法 で紹介しています。キャッシュヒット率の向上によってどれだけ節約できるかは、キャッシュ節約額の見積もりツールで確認できます。
関連記事
- GitHub Actions で Cargo と Rust のビルドをキャッシュするSwatinem/rust-cache または actions/cache を使用して、GitHub Actions で Cargo レジストリ、git 依存関係、target ディレクトリをキャッシュします。キャッシュが肥大化しないように注意します。
- GitHub Actions で Go モジュールとビルドキャッシュをキャッシュするsetup-go または actions/cache を使用して、GitHub Actions で Go モジュール(GOMODCACHE)とビルドキャッシュ(GOCACHE)をキャッシュします。キー、go.sum、キャッシュヒットの確認方法を解説します。
- GitHub Actions で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。