コンテンツへスキップ

GitHub ActionsでのJavaScript Heap Out of Memoryの修正方法

最終更新:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory は、Node.js プロセスが V8 のヒープ上限を使い切って中断したことを意味します。これは、カーネルがプロセスを強制終了する場合 (終了コード 137) とは別の失敗です。この場合は、与えられた上限が作業量に対して小さすぎるため、Node 自身が停止しています。大規模なプロジェクトでは、バンドラー、TypeScript のコンパイル、ESLint、Jest が最初にこのエラーに遭遇しがちです。npm ERR! code ENOMEM は関連するケースで、マシン自体がメモリを割り当てられない場合に発生します。

表示される正確なメッセージ

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
<--- Last few GCs --->
Aborted (core dumped)
npm ERR! code ENOMEM
npm ERR! errno ENOMEM
npm ERR! Cannot allocate memory

V8 のメッセージの後、ステップは通常ゼロ以外の終了コードで終わります。多くの場合は 134 で、これは SIGABRT です。

対策 1: ランナーの RAM を超えない範囲でヒープ上限を引き上げる

Node のデフォルトのヒープ上限は Node のバージョンとマシンのメモリに依存し、大規模なビルドではこれを超えることがあります。NODE_OPTIONS でメガバイト単位の値を指定してください:

- run: npm run build
  env:
    NODE_OPTIONS: --max-old-space-size=6144

OS や他のプロセスのための余裕を残し、その数値はランナーの RAM 以下に抑えてください。標準的なプライベートリポジトリ用の Linux ランナーは開発者のノート PC よりもメモリがかなり少ないため、ローカルでは動く上限でも、マシンがスワップに陥ったり、メモリ不足によるキルを招いたりすることがあります。使用しているマシンについては、ランナーの仕様を確認してください。

対策 2: ジョブ全体ではなく、特定のツールにだけ設定する

NODE_OPTIONS はパッケージマネージャーを含め、ステップ内のすべての Node プロセスに適用されます。特定のコマンドだけで上限を引き上げるには、次のようにします:

- run: node --max-old-space-size=6144 ./node_modules/.bin/tsc -p tsconfig.json
- run: node --max-old-space-size=4096 ./node_modules/.bin/eslint .

対策 3: メモリ使用量を減らす

  1. CI のビルドではソースマップを無効にするか、別のジョブで生成してください。
  2. 型チェック、Lint、バンドルを別々のステップまたはジョブとして実行し、それぞれのヒープが 1 つのプロセス内で積み重ならないようにしてください。
  3. Jest の場合は、ワーカー数を制限し、メモリリークを起こすワーカーを再起動するようにしてください:
- run: npx jest --maxWorkers=2 --logHeapUsage
  1. TypeScript のモノレポでは、一度にすべてを読み込むプロセスが生じないよう、プロジェクト参照と増分ビルドを使用してください。
  2. 開発時にだけ必要な大きな依存関係は、ビルドグラフから取り除いてください。

対策 4: npm ERR! code ENOMEM への対処

npm ci や npm install の実行中に ENOMEM が出る場合、パッケージの展開やインストールスクリプトの実行中にマシンのメモリが不足しています。並列に実行するステップを減らし、インストールの前にバックグラウンドでサービスを起動しないようにし、メモリの多いランナーを使用することでメモリを確保してください。ネイティブモジュールをコンパイルする postinstall スクリプトは、よくある原因です。

対策 5: RAM を増やす

上限を調整してもビルドにさらにメモリが必要な場合は、より大きなマシンを使ってください。選択肢は、GitHub の larger runner か、compiler.dev などのプロバイダーです。compiler.dev のデフォルトの Linux マシンは 8 vCPU と 16 GB です (料金を参照)。切り替えには runs-on の変更が必要です。

予防方法

  1. CI でピークメモリを記録し、ランナーの RAM の約 75% を超えたら通知するように設定してください。
  2. デフォルト値に頼らず、--max-old-space-size を明示的に設定してください。
  3. 依存関係をアップグレードする際は、バンドルサイズとテストのメモリ使用量に注意してください。
  4. 1 つのステップで重い Node プロセスは 1 つだけにしてください。

よくある質問

Node.js のデフォルトのヒープ上限はいくつですか?

Node のバージョンとシステムのメモリによって異なるため、単一の数値はありません。ランナー上で node -e "console.log(v8.getHeapStatistics().heap_size_limit / 1048576)" を実行して確認してください。

これは終了コード 137 と同じですか?

いいえ。137 はオペレーティングシステムがプロセスを強制終了したことを意味します。このエラーは、Node 自身のヒープ上限に達したときに Node が自ら中断するもので、通常は --max-old-space-size を引き上げることで解決します。

なぜローカルでは成功するのですか?

ノート PC はメモリが多く、Node がより大きなデフォルトのヒープを選ぶためです。CI のマシンは小さく、固定されています。

package.json で上限を設定できますか?

はい。例えば "build": "node --max-old-space-size=6144 node_modules/vite/bin/vite.js build" のように設定できます。ただし、ワークフローで NODE_OPTIONS を設定するほうが簡単です。