GitHub Actionsでpnpmの依存関係をキャッシュする
最終更新
GitHub Actionsでpnpmのキャッシュを有効にするには、まずpnpmをインストールし、次にactions/setup-nodeでcache: pnpmを設定します。これにより、pnpm-lock.yamlをキーとしてpnpmのコンテンツアドレス可能ストアがキャッシュされます。順序が重要です。setup-nodeは実行前にpnpmが存在している必要があるため、pnpm/action-setupをその前に配置してください。
オプション1: setup-nodeのキャッシュ
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm test
packageManagerフィールドがpackage.jsonにある場合(例: "packageManager": "pnpm@10.9.0")、pnpm/action-setupではversionを省略できます。これが最もすっきりした設定で、ローカル環境とCIの両方でpnpmのバージョンを1か所で定義できます。そうでない場合は、with: { version: 10 }を指定してください。
setup-nodeのREADME(2026年10月時点で確認)によると、pnpmキャッシュの値にはpnpm 6.10以降が必要で、pnpmが事前にインストールされている必要があります。Unable to locate executable file: pnpmと表示された場合、ステップの順序が誤っています。
オプション2: pnpm/action-setupにストアのキャッシュを任せる
pnpm/action-setupには独自のcache入力があり、デフォルトでは無効です。そのREADMEでは、pnpm-lock.yamlから生成されたキーを使ってpnpmストアのディレクトリをキャッシュすると説明されています(cache_dependency_pathで変更可能です)。
- uses: pnpm/action-setup@v6
with:
cache: true
- uses: actions/setup-node@v7
with:
node-version: 22
- run: pnpm install --frozen-lockfile
どちらか一方の仕組みを選んでください。同じストアを二重にキャッシュすると、クォータが無駄になります。
オプション3: 明示的なactions/cache
推測せず、pnpmにストアの場所を問い合わせてください。その場所はOSとpnpmのバージョンによって異なります。
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Get pnpm store path
id: pnpm-store
run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.pnpm-store.outputs.path }}
key: pnpm-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
pnpm-${{ runner.os }}-
- run: pnpm install --frozen-lockfile
hashFiles('**/pnpm-lock.yaml')のglobは、複数のロックファイルがあるリポジトリにも対応します。標準的なpnpmワークスペースではルートに1つのロックファイルしかないため、ハッシュは安定しており、依存関係が変わったときのみ変化します。
キャッシュすべきものとすべきでないもの
pnpmは各パッケージをストアに一度だけ保存し、ファイルを各プロジェクトのnode_modulesにハードリンク(またはコピー)します。この設計があるため、ストアをキャッシュするだけで十分です。
- ストアをキャッシュしてください。ネットワークからのダウンロードは最も時間がかかる部分です。
node_modulesはキャッシュしないでください。ストアへのリンクのツリーであるため、アーカイブから復元するとフルコピーになり、非常に大きくなる可能性があり、次回の実行時にストアの構造と一致しなくなることがあります。- ストアのパスをハードコードしないでください。
pnpm store pathを使用してください。
注意点があります。ハードリンクは同一のファイルシステム内でのみ機能します。ストアがワークスペースとは別のボリュームに復元される場合、pnpmはコピーにフォールバックします。これは遅くなりますが、結果は正しいままです。
ワークスペース
ワークスペースでは、ルートで一度インストールし、フィルターを使ってタスクを実行してください:
- run: pnpm install --frozen-lockfile
- run: pnpm --filter "...[origin/main]" test
フィルターを機能させるには、チェックアウトに十分な履歴が必要です。fetch-depthを含む完全な設定については、pnpmワークスペースの最速CIを参照してください。
キャッシュヒットの確認方法
- キャッシュがヒットしなかった場合、setup-nodeの後処理ステップは
Cache saved with key: ...を出力します。ヒットした場合は、復元ステップがCache restored from key: ...を出力します。 pnpm installの所要時間を計測してください。ストアがウォームな状態では、pnpmの進捗表示でパッケージがdownloadedではなくreusedとして報告されます。gh cache list --key pnpm- --limit 20で、エントリ、サイズ、最終アクセス時刻を確認できます。
マトリックスを使った完全な例
キャッシュはOSごとにキー付けされるため、Nodeのバージョンでマトリックスを組むと、ストアを共有しない限り、セルごとに1つのエントリが作成されます。pnpmストアはNodeのバージョンにほぼ依存しないため、Nodeのバージョンを含めないキーで通常は問題なく、クォータも節約できます:
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
node: [20, 22]
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node }}
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm test
setup-nodeはOS、パッケージマネージャー、ロックファイルのハッシュからキーを生成するため、両方のマトリックスセルが同じストアのエントリを復元します。ネイティブアドオンを持つパッケージはインストール時にNodeのバージョンごとに再ビルドされますが、ダウンロードは引き続きキャッシュから取得されます。実行回数に対してヒット率がどれだけの価値を持つかは、キャッシュ節約見積もりツールで確認できます。
よくある間違い
- セットアップの順序。
actions/setup-nodeをpnpm/action-setupより前に置くと、cache: pnpmは失敗します。 - pnpmバージョンの不一致。ストアの構造はメジャーバージョン間で変わります。頻繁にアップグレードする場合は、キーにpnpmのメジャーバージョンを含めてください。
--frozen-lockfileを付けずにpnpm installを使う。古いロックファイルが新しいバージョンを黙って解決するのではなく、ビルドが失敗するように、CIでは明示的に指定してください。- プルリクエストでのみキャッシュを書き込む。PRのキャッシュはPRのマージref単位で範囲が決まります。
mainからもキャッシュを作成してください。詳細はGitHub Actionsでのキャッシュを参照してください。 - 10 GBの上限を忘れる。OSとNodeの組み合わせごとに新しいエントリが作られます。キャッシュの上限を参照してください。
よくある質問
GitHubがホストするランナーでpnpmストアはどこにありますか?
ステップでpnpm store pathを実行すると、パスが表示されます。これはOSとpnpmのバージョンによって異なるため、明示的な手順ではこれを動的に読み取っています。
CIでpnpmはnpmより速いですか?
ストアがウォームな状態では、ファイルをコピーではなくリンクするため、多くの場合速くなります。効果はプロジェクトのツリーによって異なるため、同じキャッシュ状態で両方を計測してください。
pnpmストアをコミットすべきですか?
いいえ。キャッシュがその保存先として適切です。
TurborepoやNxのキャッシュはどうですか?
それらはタスクの出力をキャッシュするもので、依存関係はキャッシュしません。NxまたはTurborepoを使ったモノレポのCIを参照してください。
次のステップ
npmやYarnの設定と比較してください。インストールが速いのにジョブが依然として遅い場合、ボトルネックはCPUです。compiler.devでは、同じワークフローを8 vCPUのマシンで1分あたり$0.008で実行できます(料金を参照)。
関連記事
- 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 をキャッシュしない理由、キャッシュヒットの確認方法を解説します。