Исправление ошибки JavaScript heap out of memory в Node.js

Почему это происходит: как Node.js управляет памятью

Node.js по умолчанию ограничивает объём доступной кучи, чтобы процесс не занял всю память системы. На 64‑битных системах современный Node.js часто использует предел ~4 ГБ для кучи, которая делится на две области: новая (new space) и старая (old space). Старая область хранит объекты, которые пережили сборки мусора нескольких циклов; её размер контролируется флагом –max-old-space-size (в мегабайтах).

Схема управления памятью в Node.js: разделение кучи на old и new

Когда приложение создаёт много объектов или удерживает большие структуры в памяти (например, массивы, кэш, буферы), old space может быстро заполниться. В результате Node.js завершит процесс с сообщением «JavaScript heap out of memory».

Быстрое исправление: увеличить лимит памяти

Самый простой способ — запустить Node.js с большим лимитом старой кучи. Значение флага указывается в мегабайтах.

node --max-old-space-size=8192 yourscript.js

Команда выше даёт процессу до 8192 МБ (8 ГБ) памяти для old space. Если нужно применить настройку постоянно, задайте её через переменную окружения NODE_OPTIONS.

На Linux/macOS (bash/zsh):

export NODE_OPTIONS=--max-old-space-size=8192

На Windows (PowerShell):

setx NODE_OPTIONS "--max-old-space-size=8192"

Или через классический интерфейс: Панель управления → Система → Дополнительные параметры системы → Переменные среды → Создать переменную: имя NODE_OPTIONS, значение –max-old-space-size=8192.

Важно: увеличивать лимит имеет смысл как временную меру. Если приложение постоянно требует всё больше памяти, это может скрывать утечку памяти или неэффективную архитектуру.

Диагностика: как понять, что именно потребляет память

Включите детальный лог сборки мусора:

node --trace-gc --trace-gc-verbose --log-timer-events --max-old-space-size=4096 yourscript.js

Создайте дамп heap при аварии и проанализируйте его (Chrome DevTools / Heap snapshot):

node --max-old-space-size=4096 --abort-on-uncaught-exception --trace-gc yourscript.js
# при аварии используйте llnode / node-report / heapdump для создания snapshot

Используйте профайлеры: Chrome DevTools (Inspector), clinic.js, 0x или встроенные профили памяти в IDE.

Альтернативные подходы (когда увеличение лимита не помогает)

Оптимизация кода: освобождайте ссылки на большие объекты, избегайте глобальных кэшей.
Потоковая обработка: вместо чтения/парсинга целых файлов в память — используйте стримы (streams) и буферы фиксированного размера.
Разбиение задач: используйте кластеризацию (cluster) или worker_threads для распределения нагрузки между процессами, каждый с собственным лимитом памяти.
Внешнее хранилище: храните большие данные во внешних сервисах (БД, Redis, файловая система) вместо памяти процесса.

Мини‑методика: шаги для устойчивого решения

Воспроизведите проблему локально с теми же данными или нагрузкой.
Временно увеличьте –max-old-space-size, чтобы подтвердить причину.
Соберите heap snapshot и профиль CPU/memory.
Найдите удерживающие объекты (retainers), исправьте утечки или переработайте алгоритм.
Внедрите потоковую обработку или разбейте задачу на процессы.
Напишите нагрузочные тесты и мониторинг памяти в продакшне.

Ментальные модели и эвристики

Правило 1: увеличение лимита — временная мера. Если память растёт со временем — это утечка.
Правило 2: большой пиковый объём памяти ≠ утечка. Пиковая загрузка может быть нормальной (например, импорт больших данных).
Правило 3: разделение ответственности. Если работа можно распараллелить — используйте несколько процессов вместо одного монолита с гигабайтами на куче.

Критерии приёмки (когда можно считать проблему решённой)

Приложение больше не падает с «heap out of memory» при реальной нагрузке.
Потребление памяти остаётся стабильным и входит в ожидаемые SLO/SLA.
Наличие мониторинга и алертов по памяти, профайлов и регрессионных тестов.

Примеры типичных ошибок и когда описанные шаги не сработают

Приложение использует стороннюю нативную библиотеку, которая выделяет память вне V8 (например, большие C++ буферы): флаг –max-old-space-size не решит проблему — нужно профилировать нативную часть.
32‑битная сборка Node.js: лимиты памяти значительно меньше; решение — перейти на 64‑битную сборку.
Если система в целом испытывает дефицит RAM, то увеличение лимита приведёт к свопингу и деградации производительности — вместо этого масштабируйте горизонтально или увеличьте физическую память.

Быстрый чек-лист для разработчика

Воспроизводится ли ошибка локально с теми же данными?
Повышение –max-old-space-size временно исправляет ли падение?
Создан ли heap snapshot и проанализирован ли он?
Используются ли стримы вместо загрузки всего в память?
Есть ли мониторинг и алерты по использованию памяти?

Факты (ключевые числа)

Стандартный предел кучи на 64‑битных версиях Node.js часто около 4 ГБ.
Флаг –max-old-space-size принимает значение в мегабайтах (например, 8192 = 8 ГБ).

Короткий словарь

old space — часть кучи V8 для объектов, прошедших несколько циклов GC.
heap snapshot — снимок кучи процесса для последующего анализа в профайлере.
GC (Garbage Collector) — сборщик мусора V8.

Быстрая инструкция для DevOps (SOP)

При обнаружении ошибки: переключите автосборщик на аварийные логи и включите –trace-gc.
Если просто нужен временный буфер — увеличьте NODE_OPTIONS на тестовом окружении.
Соберите heap snapshot и отправьте команде разработки.
Разверните фикс и мониторьте память 24–72 часа.

Вывод

Ошибка «JavaScript heap out of memory» указывает на исчерпание старой кучи V8. Увеличение лимита через –max-old-space-size помогает быстро, но для стабильного результата применяйте профилирование, потоковую обработку данных и архитектурные улучшения. Набор инструментов: heap snapshot, профайлеры, streaming API и разделение нагрузки между процессами.

Важно: увеличивайте лимит только после тщательной диагностики и с мониторингом.