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: メモリ使用量を減らす
- CI のビルドではソースマップを無効にするか、別のジョブで生成してください。
- 型チェック、Lint、バンドルを別々のステップまたはジョブとして実行し、それぞれのヒープが 1 つのプロセス内で積み重ならないようにしてください。
- Jest の場合は、ワーカー数を制限し、メモリリークを起こすワーカーを再起動するようにしてください:
- run: npx jest --maxWorkers=2 --logHeapUsage
- TypeScript のモノレポでは、一度にすべてを読み込むプロセスが生じないよう、プロジェクト参照と増分ビルドを使用してください。
- 開発時にだけ必要な大きな依存関係は、ビルドグラフから取り除いてください。
対策 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 の変更が必要です。
予防方法
- CI でピークメモリを記録し、ランナーの RAM の約 75% を超えたら通知するように設定してください。
- デフォルト値に頼らず、
--max-old-space-sizeを明示的に設定してください。 - 依存関係をアップグレードする際は、バンドルサイズとテストのメモリ使用量に注意してください。
- 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 を設定するほうが簡単です。
関連記事
- Cache Service Responded With 429: 修正方法GitHub Actions の「Failed to restore: Cache service responded with 429」を修正します。キャッシュへのリクエストが多すぎる場合の対処法です。actions/cache を更新し、復元は何度行っても構いませんが、保存は一度だけにしてください。
- fatal: could not read Username for github.com: 修正方法GitHub Actionsで"fatal: could not read Username for 'https://github.com'"を解決する方法:プライベートリポジトリ、サブモジュール、gitの依存関係にはトークンが必要です。
- Invalid Workflow File: YAML構文エラーの修正方法GitHub Actionsで"Invalid workflow file"と"You have an error in your yaml syntax"を解決する方法:インデント、予期しない値、不正な式をactionlintで確認します。
- GitHub ActionsでのPermission Denied (publickey)の修正方法GitHub Actionsで"git@github.com: Permission denied (publickey)"を解決する方法:SSHキーまたはデプロイキーを追加するか、プライベートリポジトリ向けにHTTPSトークンへ切り替えます。