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

Как Node.js управляет памятью

Node.js по умолчанию ограничивает объём кучи, чтобы процессы не занимали всю память системы. Конкретные лимиты зависят от архитектуры ОС и версии Node.js. Для 64-битных версий Node.js современный предел кучи составляет примерно 4 ГБ. Куча делится на две области: new space (молодая область) и old space (старая область).

Старая область (old space) хранит долго живущие объекты. Её размер управляется флагом –max-old-space-size (значение в мегабайтах). Если приложение создаёт много объектов и стареющая область быстро заполняется, Node.js выбросит ошибку «JavaScript heap out of memory» и завершит процесс.

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

Чтобы временно устранить проблему, запустите Node.js с большим лимитом кучи:

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

Эта команда разрешит скрипту yourscript.js использовать до 8192 МБ (8 ГБ) памяти.

Чтобы задать флаг глобально в окружении на Linux/macOS, используйте:

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

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

Если вы используете процесс-менеджер pm2, добавьте аргумент Node.js:

pm2 start app.js --node-args="--max-old-space-size=8192"

В Docker указывайте флаг в команде запуска или в Dockerfile:

CMD ["node", "--max-old-space-size=8192", "app.js"]

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

Когда увеличение лимита не помогает — причины и что делать

• Утечки памяти. Приложение постоянно удерживает ссылки на объекты. Увеличение лимита только отсрочит сбой. Решение: найти утечку и исправить код.
• Одновременная загрузка больших объёмов данных в память (например, чтение больших файлов целиком). Решение: переключиться на потоковую обработку или батчи.
• Неправильное поведение сторонних библиотек, которые создают большое количество объектов.

Методика поиска и устранения проблемы (шаги)

1. Запустите приложение с профайлером: node –inspect или node –inspect-brk и подключитесь через Chrome DevTools.
2. Сделайте heap snapshot и сравните два снимка (до и после определённой операции).
3. Ищите объекты, чьё количество растёт со временем и которые удерживаются по ссылке.
4. Проверяйте сторонние модули: временно замените или обновите зависимости.
5. Тестируйте исправления под нагрузкой или на реальном наборе данных.

Инструменты и сниппеты (cheat sheet)

• Запуск с инспектором:

node --inspect-brk --max-old-space-size=4096 app.js

• PM2:

pm2 start app.js --node-args="--max-old-space-size=4096"

• Docker (пример):

FROM node:18
WORKDIR /app
COPY . .
CMD ["node", "--max-old-space-size=4096", "server.js"]

• Экспорт переменной окружения (Linux/macOS):

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

Альтернативные подходы к уменьшению потребления памяти

• Потоковая обработка (streams) вместо чтения файлов полностью в память.
• Обработка данных батчами (порциями), чтобы ограничить объём одновременно хранимых объектов.
• Использование внешних хранилищ (Redis, баз данных) для больших промежуточных наборов данных.
• Offloading: выполнять тяжёлую обработку в сервисах/очередях, распределяя нагрузку.

Роль‑ориентированные чеклисты

Разработчик:

• Запустить приложение локально с –inspect и получить heap snapshot.
• Проверить участки кода с возможными глобальными кэшами и коллекциями.
• Внедрить потоковую обработку для работы с файлами и сетевыми потоками.

Системный администратор / DevOps:

• Убедиться, что в конфигурации процесса указан корректный NODE_OPTIONS или флаги pm2.
• Настроить мониторинг памяти (метрики, алерты) и рестарт процессов при OOM.
• При использовании контейнеров установить лимиты памяти и резервы.

Руководитель тестирования:

• Подготовить нагрузочные тесты, имитирующие реальные объёмы данных.
• Проверять, не увеличивается ли используемая память со временем.

Критерии приёмки

• Приложение работает под целевой нагрузкой без ошибки OOM в течение требуемого интервала (например, 24 часа).
• Пиковое потребление памяти не превышает установленного лимита на 15–20 %.
• Наличие автоматических тестов или профайлов, подтверждающих отсутствие регрессий.

Короткий глоссарий

• Old space — старая область кучи, где живут долгоживущие объекты.
• New space — молодая область кучи, куда попадают недавно созданные объекты.
• OOM — out of memory, ошибка исчерпания памяти.
• Heap snapshot — снимок состояния кучи для анализа распределения объектов.

Примеры, когда повышение лимита — плохая идея

• Если проблема вызвана утечкой, увеличение лимита только отложит падение и увеличит потребление ресурсов на сервере.
• В контейнерах увеличение лимита без изменения лимитов контейнера может привести к вмешательству в другие сервисы.

Итог

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

Примечание: посетите ITtutoria для статей и руководств по профайлингу и оптимизации Node.js.