コンテンツへスキップ

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のバージョンごとに再ビルドされますが、ダウンロードは引き続きキャッシュから取得されます。実行回数に対してヒット率がどれだけの価値を持つかは、キャッシュ節約見積もりツールで確認できます。

よくある間違い

  1. セットアップの順序。actions/setup-nodeをpnpm/action-setupより前に置くと、cache: pnpmは失敗します。
  2. pnpmバージョンの不一致。ストアの構造はメジャーバージョン間で変わります。頻繁にアップグレードする場合は、キーにpnpmのメジャーバージョンを含めてください。
  3. --frozen-lockfileを付けずにpnpm installを使う。古いロックファイルが新しいバージョンを黙って解決するのではなく、ビルドが失敗するように、CIでは明示的に指定してください。
  4. プルリクエストでのみキャッシュを書き込む。PRのキャッシュはPRのマージref単位で範囲が決まります。mainからもキャッシュを作成してください。詳細はGitHub Actionsでのキャッシュを参照してください。
  5. 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で実行できます(料金を参照)。

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

無料で試す