Сборка завершается ошибкой: FATAL ERROR: Reached heap limit, JavaScript heap out of memory

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

Сообщение «JavaScript heap out of memory» при сборке проекта (webpack, Vite, Next.js, tsc) означает, что процесс Node.js исчерпал лимит памяти кучи. Сборка больших проектов требует больше памяти, чем доступно по умолчанию.

Увеличение лимита — быстрое решение, но стоит также уменьшить потребление памяти самой сборкой.

Сборка держит в памяти граф модулей и исходные карты. Когда объём превышает лимит кучи V8, процесс завершается.

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

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

1. Увеличьте лимит памятиВ терминале проекта (VS Code → «Терминал» → «Новый терминал») запустите штатную команду сборки, например npm run build, и найдите в выводе FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory. Это именно исчерпание кучи Node.js, а не всегда физической оперативной памяти. Выполните node -v и node -p "process.arch", посмотрите package.json и сценарий сборки. Сохраните точный лог, не публикуя секреты из переменных окружения.
2. Проверьте памятьПрежде чем повышать лимит, проверьте доступную оперативную память и ограничения процесса: Windows — Ctrl+Shift+Esc → «Производительность» → «Память», macOS — «Мониторинг системы» → «Память», Linux — free -h; для контейнера проверьте его лимит памяти в конфигурации. Для теста на машине с достаточным запасом задайте переменную на один запуск: Linux/macOS NODE_OPTIONS=--max-old-space-size=4096 npm run build; в PowerShell $env:NODE_OPTIONS='--max-old-space-size=4096'; npm run build, затем Remove-Item Env:NODE_OPTIONS. 4096 — пример в МиБ, не превышайте возможности машины и не ставьте значение наугад в общей среде.

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

   Задаёт лимит 4 ГБ для процесса Node. Должно хватать физической памяти. В Windows: set NODE_OPTIONS=--max-old-space-size=4096 отдельной командой.

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

3. Отключите source mapsЕсли сборка всё ещё исчерпывает кучу, найдите этап, на котором растёт память (транспиляция, создание карт исходного кода, минификация). Откройте конфигурацию вашего сборщика и по его официальному руководству временно отключите генерацию production source maps только для тестовой сборки. В Webpack это настройка devtool, в Vite — build.sourcemap; другие инструменты используют другие параметры. Повторите сборку и сравните использование памяти, учитывая, что отсутствие карт ухудшает отладку.
4. Обновите инструментыПроверьте версии инструментов без изменения зависимостей: npm ls --depth=0 и npm outdated. Сравните совместимость Node.js с версией сборщика по документации проекта. Не запускайте бездумно npm update или переход на новый основной выпуск — изменится граф зависимостей. Если обновление действительно требуется, создайте отдельную ветку Git, сохраните package-lock.json, установите совместимые версии и прогоните тесты; при регрессии откатите отдельный коммит.
5. Очистите кэшПри подозрении на испорченный кэш сначала остановите сборку, а затем очистите только документированный кэш используемого сборщика, например конкретный каталог node_modules/.cache у Webpack, если он существует. Если проект использует npm и есть package-lock.json, npm ci пересоздаст node_modules, удалив этот каталог; это отдельная операция, которую проводят после сохранения важных локальных изменений. Снова запустите сборку; если рост памяти повторяется даже на достаточном лимите, выполните профилирование Node и проверьте плагины на утечки.

#Если не помогло

Не ставьте лимит больше доступной памяти: система начнёт использовать подкачку и сборка замедлится. В CI закрепите значение в конфигурации задачи.

#Как увеличить лимит

Лимит кучи можно временно повысить только при достаточной физической памяти и лимитах контейнера/сборочного агента. Синтаксис отличается в PowerShell, cmd и оболочках Linux/macOS, поэтому используйте команду для вашей системы из шагов выше; после эксперимента верните исходные параметры.

#Как снизить потребление

Оптимизация сборки зависит от инструмента: изучите отчёт расхода памяти и конфигурацию Webpack, Vite, Next.js или TypeScript. Возможные меры — сократить зависимости, изменить построение карт исходного кода, проверить память плагинов и кэширование. Параметры productionSourceMap, sourcemap, thread-loader, incremental и skipLibCheck не являются универсальными и способны изменить результат сборки; применяйте только поддерживаемые настройки вашего проекта.