Node.js: FATAL ERROR: JavaScript heap out of memory

#Что означает ошибка

V8 ограничивает размер «кучи» для старых объектов: по умолчанию от 2 до 4 ГБ на 64-битных системах (зависит от версии Node и объёма ОЗУ; в Node 12+ лимит вычисляется по доступной памяти). Когда программа держит в памяти больше данных, чем помещается, Node завершается с ошибкой heap out of memory. Типичные сценарии: сборка большого фронтенда (webpack, Vite, Next.js), чтение огромных файлов целиком, накапливающиеся в памяти кэши, утечки.

#Причины и решения

#Пошаговое решение

1. Узнайте текущий лимитОткройте терминал в папке проекта: в VS Code выберите «Терминал → Создать терминал», в Windows можно открыть PowerShell через меню «Пуск». Выполните node --version, затем node -e "console.log(Math.round(require('v8').getHeapStatistics().heap_size_limit/1024/1024))". Второе число — лимит кучи V8 в МиБ, а не вся доступная оперативная память. Сравните его с объёмом ОЗУ в «Диспетчере задач → Производительность → Память» (Windows) или с данными системы. Если node не найден, сначала проверьте установку Node.js и путь PATH.
2. Увеличьте лимитЕсли ошибка возникла во время сборки npm run build, сохраните результаты работы и в терминале проекта временно увеличьте лимит только для этого запуска. Linux/macOS: NODE_OPTIONS=--max-old-space-size=4096 npm run build; PowerShell: $env:NODE_OPTIONS='--max-old-space-size=4096'; npm run build. Значение 4096 — пример для машины с достаточной свободной памятью; на компьютере с 4 ГиБ ОЗУ использовать его неразумно. При успешной сборке проблема была в ограничении кучи; при аварийном завершении ОС проверьте суммарную память контейнера и систему подкачки, а не увеличивайте число снова.
3. Зафиксируйте в package.jsonЕсли приложение регулярно требует больший лимит и измерения показывают, что памяти достаточно, согласуйте изменение команды запуска с разработчиком. Откройте package.json и найдите раздел scripts: установите NODE_OPTIONS перед запуском через сценарий среды (например, cross-env как отдельную установленную зависимость), либо запустите точный JS-файл командой node --max-old-space-size=4096 путь/к/файлу.js. Не подставляйте node_modules/vite/bin/vite.js для любого сборщика: расположение исполняемого файла зависит от версии. Проверьте, что обычная сборка снова работает и значение ограничено только нужным процессом.
4. Найдите утечкуЕсли объём памяти растёт при длительной работе сервера, исследуйте утечку, а не повышайте лимит бесконечно. В копии проекта или безопасном испытательном окружении запустите node --inspect app.js, заменив app.js реальной точкой входа. В Chrome откройте chrome://inspect, выберите процесс Node.js → «Inspect» → вкладка Memory, сделайте снимки кучи до и после повторения сценария. Сравните удерживаемые объекты. Не публикуйте отладочный порт в Интернет и не подключайте инспектор к чужому рабочему процессу; при отсутствии разрешения передайте разработчику журналы и шаги воспроизведения.
5. Обрабатывайте данные потокамиЕсли ошибка возникает при чтении большого файла, откройте в проекте участок, где используются readFileSync, readFile или собирается огромный массив, и проверьте, не загружаются ли все данные целиком. Для построчной обработки текста используйте createReadStream вместе с readline, для передачи данных — потоковую обработку с контролем ошибок. Сначала испытайте изменение на небольшой копии файла и сравните результат; строки с многобайтными символами нельзя произвольно разрезать по байтам. Если код не ваш, сообщите разработчику путь к файлу и объём обрабатываемых данных.
6. Ограничьте параллелизмЕсли ошибка появляется лишь во время сборки или тестов с множеством процессов, проверьте число одновременно запускаемых задач в конфигурации именно вашего инструмента. Для Jest найдите параметр maxWorkers и попробуйте ограничить число работников; для Webpack проверьте документацию по parallelism, если этот параметр поддерживается в вашей конфигурации. Изменение TypeScript incremental само по себе не гарантирует уменьшения потребления памяти. После каждого отдельного изменения запустите прежнюю команду и зафиксируйте длительность и пиковое потребление; не смешивайте несколько настроек одновременно.
7. Обновите Node.jsПроверьте поддерживаемую проектом версию Node.js: посмотрите .nvmrc, поле engines в package.json и руководство к сборщику. При несовместимости установите подходящую поддерживаемую версию через официальный установщик или выбранный менеджер версий и переоткройте терминал. Выполните node --version, повторите сборку и убедитесь, что результат воспроизводится. Если даже при достаточном лимите размер кучи растёт без остановки, верните прежнюю версию/настройки и оформите сообщение об утечке с журналом ошибки и измерениями.
8. Первая и вторая команды — только проверка

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Первая и вторая команды — только проверка. Последняя — отдельный вариант запуска для Linux/macOS, НЕ вводите её в PowerShell. Для PowerShell см. шаг 2.

   node --version

   node -e "console.log(Math.round(require('v8').getHeapStatistics().heap_size_limit/1024/1024))"

   # Linux/macOS, только в терминале проекта при достаточной ОЗУ:

   NODE_OPTIONS=--max-old-space-size=4096 npm run build

Если сборка падает в Docker/CI, проверьте лимит памяти контейнера: Node не знает о cgroup-лимите в старых версиях, и ядро убивает процесс (OOM killer) раньше, чем V8 сообщит об ошибке (Killed в выводе). Используйте docker stats и увеличьте память либо включите swap. Подробнее о ключах — в документации Node.js.