#Что означает ошибка
heap out of memory
Сообщение FATAL ERROR: Reached heap limit Allocation failed — JavaScript heap out of memory означает, что процесс Node.js исчерпал лимит памяти, отведённый движку V8 под кучу. По умолчанию лимит зависит от версии Node и доступной памяти (в 64-разрядных системах — примерно 2–4 ГБ), и тяжёлые сборки или обработка больших данных его превышают.
Увеличение лимита — быстрое решение, но если приложение действительно «течёт», оно упадёт позже. Поэтому сначала определите, что нужно приложению: больше памяти (сборка большого фронтенда) или исправление утечки (серверный процесс, растущий со временем).
Увеличьте --max-old-space-size и найдите утечку.
#Причины и решения
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Мало памятиЛимит. | Проявляется как «heap out of memory» или близкий по смыслу сбой. | Увеличьте. |
| УтечкаКод. | Проявляется как «heap out of memory» или близкий по смыслу сбой. | Найдите. |
| Большие данныеПамять. | Проявляется как «heap out of memory» или близкий по смыслу сбой. | Потоки. |
| СборкаWebpack. | Проявляется как «heap out of memory» или близкий по смыслу сбой. | Увеличьте. |
#Пошаговое решение
- Проверьте доступную память и момент переполненияЗафиксируйте команду запуска и лог
JavaScript heap out of memory. На Windows откройте «Диспетчер задач → Производительность → Память», в Linux выполнитеfree -h; отдельно посмотрите лимит памяти контейнера, если Node.js работает в Docker. Увеличивать лимит кучи сверх доступной памяти опасно. - Определите текущий лимит Node.jsВ терминале выполните
node -e "const v8=require('node:v8'); console.log(Math.round(v8.getHeapStatistics().heap_size_limit/1048576))". Это примерный предел кучи в МиБ; он не равен общему потреблению процесса. Сравните с памятью компьютера и другими запущенными сервисами. - Временно увеличьте лимит при наличии запасаЕсли в компьютере достаточно RAM, для теста запускайте
node --max-old-space-size=4096 app.js; для npm-сборки на UnixNODE_OPTIONS=--max-old-space-size=4096 npm run build, на Windows PowerShell$env:NODE_OPTIONS="--max-old-space-size=4096"; npm run build. Значение 4096 — пример, а не универсальная норма. - Проверьте утечки и объём входных данныхЕсли память растёт без ограничения, запустите отладку Node.js на тестовой машине с
node --inspect app.js, откройтеchrome://inspectи сравните снимки кучи. Для чтения больших файлов используйте потоки вместо загрузки всего содержимого в память. Проверьте повторной сборкой при одинаковых входных данных; не принимайте увеличение лимита за исправление утечки.
#Увеличение лимита
Задайте параметр --max-old-space-size в мегабайтах: node --max-old-space-size=4096 app.js. Для npm-скриптов используйте переменную окружения NODE_OPTIONS=--max-old-space-size=4096. Не ставьте значение больше физической памяти сервера, иначе процесс будет убит ядром (OOM-killer).
#Сборка проекта
Webpack, Vite и TypeScript на больших проектах требуют много памяти. Включите кэширование, отключите карты исходников в production при нехватке памяти, разбейте сборку на части и обновите инструменты — новые версии потребляют меньше. В CI увеличьте память раннера.
#Поиск утечек
В серверных приложениях растущая кривая памяти — признак утечки: глобальные кэши без ограничения, не удаляемые слушатели событий, замыкания, накапливающие данные. Используйте профилировщик (node --inspect, Chrome DevTools, heapdump) и сравнивайте снимки кучи. Обрабатывайте большие файлы потоками, а не целиком.
node -e "const v8=require('node:v8'); console.log(Math.round(v8.getHeapStatistics().heap_size_limit/1048576))"