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とディスクの性能に依存します。これはキャッシュの問題ではなく、マシンの問題です。
キャッシュヒットの確認方法
- ジョブログでsetup-nodeまたはcacheステップを開きます。ヒットした場合は
Cache restored from key: ...と表示されます。ミスの場合はCache not found for input keys: ...と表示されます。 actions/cacheでは、cache-hitの出力は完全一致のキーでのみ'true'になります。restore-keysによる部分一致では、ファイルが復元されていても'false'になります。- ミスの場合は、post stepで
Cache saved with key: ...という表示を確認してください。 - CLIで存在するキャッシュを一覧表示します:
gh cache list --key npm- --limit 20
同じロックファイルでワークフローを2回実行してください。2回目は復元されたと表示され、インストールステップの時間が目に見えて短くなるはずです。
よくある間違い
npm installの代わりにnpm ciを使う。npm installは lockfile を書き換えることがあるため、キャッシュのキーとインストールされたツリーがずれてしまいます。- ロックファイルがコミットされていない。
hashFilesは空文字列を返し、すべての実行で同じキーが使われるため、キャッシュは更新されません。この場合setup-nodeはエラーで失敗しますが、これは有用な挙動です。 - 異なるNodeのメジャーバージョンが同じキーを共有している。 マトリクスビルドを使う場合は、バージョンをキーに含めてください。
- プルリクエストでのみキャッシュが作成される。 PRのキャッシュはマージref単位でスコープされ、他のPRからは参照できません。各PRがウォームなキャッシュを読めるよう、
mainへのpushでも同じキャッシュステップが実行されるようにしてください。 - 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のマシンでジョブを実行します。詳しくは料金をご覧ください。
関連記事
- 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でpipの依存関係をキャッシュするsetup-python または actions/cache を使って GitHub Actions で pip をキャッシュします。より高速な uv の選択肢もあります。キーの設計、キャッシュすべきでないもの、キャッシュヒットの確認方法を解説します。