コンテンツへスキップ

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

最終更新

GitHub Actions で npm の依存関係をキャッシュするには、cache: npm を actions/setup-node に追加し、npm ci でインストールします。これにより、npm のダウンロードディレクトリ(~/.npm)がキャッシュされ、キーは package-lock.json に基づきます。キーやパスを細かく制御したい場合は、下記の明示的な actions/cache の形式を使用すると同じ結果が得られます。

このページはnpm専用のレシピです。キー、スコープ、restore-keysの仕組み全般については、先にGitHub Actionsのキャッシュをお読みください。

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

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test

このアクションは、リポジトリのルートにあるpackage-lock.json(またはnpm-shrinkwrap.json)のハッシュからキーを生成します。モノレポの場合やロックファイルがルートにない場合は、正しいファイルを指定してください:

- uses: actions/setup-node@v7
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: |
      package-lock.json
      apps/web/package-lock.json

cache-dependency-pathはcacheが設定されている場合にのみ有効です。setup-nodeのREADME(2026年10月確認)によると、package.jsonのpackageManagerフィールドでnpmが宣言されている場合、npmのキャッシュも自動で有効になることがあります。その自動有効化を無効にするにはpackage-manager-cache: falseを設定します。cache: npmを明示的に設定すると、動作がより分かりやすくなります。

方法2: 明示的なactions/cache

独自のキーを使いたい場合、復元と保存を分けたい場合、またはsetup-nodeを使っていない場合にこの方法を使用してください。

- uses: actions/setup-node@v7
  with:
    node-version: 22
- name: Get npm cache directory
  id: npm-cache
  run: echo "dir=$(npm config get cache)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.npm-cache.outputs.dir }}
    key: npm-${{ runner.os }}-node22-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-node22-
- run: npm ci

npmにキャッシュディレクトリを問い合わせると、Windowsランナーでは誤りになる~/.npmをハードコーディングせずに済みます。キーにはOS、Nodeのメジャーバージョン、ロックファイルのハッシュが含まれます。restore-keysの行があるため、パッケージを1つ変更しただけなら前日のキャッシュの大部分が復元され、npm ciは差分のみをダウンロードします。

node_modulesではなく~/.npmをキャッシュする

node_modulesをキャッシュするという一般的なアドバイスは、npmでは逆効果になります。npm ciはインストール前にnode_modulesを削除するため、復元したコピーは捨てられてしまいます。そのため、ダウンロードと展開にかかった時間に加えて、再構築にも時間を取られます。

一方、~/.npmをキャッシュする場合は違います。npm ciは依然としてすべてのパッケージを展開しますが、レジストリからではなくローカルディスク上のtarballを読み込みます。ネットワークにかかる時間が削減されるのはこの部分です。

キャッシュnpm ciで利用可能備考
~/.npmあり小さく、Nodeのバージョンをまたいでも安全
node_modulesなしインストール時に削除される。ネイティブモジュールはNodeのバージョン間で壊れる
.next/cache, .vite, .eslintcacheはい(別途)依存関係ではなく、ビルドやlintのキャッシュ

キャッシュ後もインストール時間が依然として問題になる場合、展開工程はCPUとディスクの性能に依存します。これはキャッシュの問題ではなく、マシンの問題です。

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

  1. ジョブログでsetup-nodeまたはcacheステップを開きます。ヒットした場合はCache restored from key: ...と表示されます。ミスの場合はCache not found for input keys: ...と表示されます。
  2. actions/cacheでは、cache-hitの出力は完全一致のキーでのみ'true'になります。restore-keysによる部分一致では、ファイルが復元されていても'false'になります。
  3. ミスの場合は、post stepでCache saved with key: ...という表示を確認してください。
  4. CLIで存在するキャッシュを一覧表示します:
gh cache list --key npm- --limit 20

同じロックファイルでワークフローを2回実行してください。2回目は復元されたと表示され、インストールステップの時間が目に見えて短くなるはずです。

よくある間違い

  1. npm install の代わりに npm ci を使う。 npm install は lockfile を書き換えることがあるため、キャッシュのキーとインストールされたツリーがずれてしまいます。
  2. ロックファイルがコミットされていない。 hashFilesは空文字列を返し、すべての実行で同じキーが使われるため、キャッシュは更新されません。この場合setup-nodeはエラーで失敗しますが、これは有用な挙動です。
  3. 異なるNodeのメジャーバージョンが同じキーを共有している。 マトリクスビルドを使う場合は、バージョンをキーに含めてください。
  4. プルリクエストでのみキャッシュが作成される。 PRのキャッシュはマージref単位でスコープされ、他のPRからは参照できません。各PRがウォームなキャッシュを読めるよう、mainへのpushでも同じキャッシュステップが実行されるようにしてください。
  5. postinstallで取得されるバイナリ。 Playwright、Cypress、Puppeteerなどのパッケージは、~/.npmの外にブラウザをダウンロードします。これらのディレクトリは別途キャッシュしてください。詳しくはPlaywrightテストが遅いとCypressテストが遅いを参照してください。

サイズと削除

一般的なnpmキャッシュは数百MB程度です。リポジトリの上限は10GBで、古いエントリは最近最も使われていないものから順に削除され、7日間使われていないものは削除されます。複数のNodeバージョンやOSにまたがるマトリクスは、エントリ数を急速に増やします。クォータを何が使っているかを確認する方法は、キャッシュの上限と削除を参照してください。

キャッシュヒット時の削減時間の見積もりでは、ヒット率を改善した場合に何分節約できるかを確認できます。

よくある質問

CIではnpm ciとnpm installのどちらを使うべきですか?

npm ciを使用してください。ロックファイルの内容を正確にインストールし、package.jsonとロックファイルが一致しない場合は失敗します。また、クリーンなインストールでは高速です。

setup-nodeのキャッシュはフォークからのプルリクエストでも機能しますか?

ベースブランチが作成したキャッシュは復元されます。フォークからのPRによる保存はGitHubのトークン権限によって制限されるため、キャッシュの作成はmainに頼ってください。

npmキャッシュは復元されるのに、npm ciがまだ遅いのはなぜですか?

キャッシュが取り除くのはダウンロードであり、展開やライフサイクルスクリプトの実行ではありません。postinstallスクリプトに費やされている時間を確認するか、より高速なランナーを試してください。

異なるワークフロー間でnpmのキャッシュを共有できますか?

はい。キャッシュはリポジトリ単位で管理されます。キーとパスが同じであれば、同じキャッシュが使われます。

次のステップ

pnpmやYarnも使っている場合は、pnpmのキャッシュとYarnのキャッシュを参照してください。修正方法の一覧はGitHub Actionsを高速化する方法をお読みください。compiler.devでは、依存関係のキャッシュが準備された8 vCPUのマシンでジョブを実行します。詳しくは料金をご覧ください。

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

無料で試す