К содержимому
Войти

Node.js Road Map

🧠 Память, GC и профилирование

Долгоживущий Node-сервис часто падает не от ошибки в коде, а от памяти: график RSS ползёт вверх неделю, потом под перезапускается с OOMKilled. Чтобы разобраться, нужно понимать, как V8 раскладывает объекты по куче и когда их убирает, что значит каждое поле process.memoryUsage() и как снять и прочитать heap snapshot. Когда разговор на собеседовании доходит до прода, любимый вопрос здесь — почему процесс убили, хотя heapUsed был далеко от лимита

🧠 Как устроена куча V8

Все JS-объекты, строки и замыкания живут в куче V8. Она разделена на поколения, потому что работает гипотеза поколений: большинство объектов умирает молодыми. Промежуточные массивы из map и filter, DTO, распарсенный JSON запроса становятся мусором, как только обработчик вернул ответ, а кэш конфигурации живёт до перезапуска

Молодое поколение

Новый объект попадает в new space, и выделение там почти бесплатное: V8 сдвигает указатель на размер объекта. New space поделена на две semi-space, рабочую и пустую

Когда рабочая половина заполнилась, запускается малая сборка scavenger. Он копирует живые объекты в пустую половину, и старая половина целиком становится свободной. Мёртвые объекты он не трогает, поэтому цена сборки зависит от числа выживших, а не от количества мусора. Объект, переживший две малые сборки, переезжает в старое поколение

Ссылки из старых объектов на молодые отмечает write barrier, поэтому малая сборка не обходит всю старую кучу. Размер semi-space зависит от лимита памяти: по документации Node при лимите 512 МиБ это 1 МиБ, при лимитах до 2 ГиБ меньше 16 МиБ. Его меняют флагом --max-semi-space-size, на сервисах с массой короткоживущих объектов это иногда ускоряет работу

Старое поколение

В old space живут объекты, пережившие молодость: кэши, пулы соединений, модули, долгие замыкания. Копировать их туда-сюда дорого, поэтому здесь работает mark-sweep-compact:

  1. Маркировка: от корней (глобальный объект, стек, хэндлы) V8 проходит по всем ссылкам и помечает достижимые объекты
  2. Очистка: дыры от непомеченных объектов попадают в списки свободных блоков по размерам, новые объекты займут их
  3. Уплотнение: сильно фрагментированные страницы эвакуируются, живые объекты переносятся плотнее. Остальные страницы только очищаются

Сборщик удаляет то, до чего нельзя дойти от корней. Утечка в JS почти всегда означает, что ненужный объект остался достижимым: на него ссылается Map, слушатель или замыкание

Orinoco: чтобы паузы были короткими

Большая сборка целиком на главном потоке заморозила бы сервис на сотни миллисекунд. Сборщик V8 Orinoco выносит работу из паузы тремя способами

СпособЧто происходитЧто даёт
ПараллельныйJS стоит, сборку делают главный поток и вспомогательные одновременнопауза короче во столько раз, сколько потоков помогают
Инкрементальныйглавный поток делает маркировку маленькими кусками между кусками JSпаузы мельче, но суммарное время на главном потоке то же
Конкурентныйвспомогательные потоки маркируют и чистят, пока JS работаетработа уходит с главного потока совсем

Сейчас у порога кучи стартует конкурентная маркировка, а write barrier ловит ссылки, которые JS меняет по ходу. Потом короткая пауза на финализацию и параллельное уплотнение, очистка снова в фоне. Если куча подошла к лимиту, V8 собирает всё чаще, и сервис тормозит ещё до падения

📏 Что показывает process.memoryUsage()

const { rss, heapTotal, heapUsed, external, arrayBuffers } = process.memoryUsage()
ПолеЧто это
rssвся память процесса в физической RAM: куча V8, код, стеки потоков, нативные буферы, память C++ и аддонов
heapTotalсколько V8 сейчас выделил под кучу
heapUsedсколько из этого занято объектами, живыми или ещё не собранными
externalпамять C++-объектов, привязанных к JS-объектам, в том числе данные Buffer
arrayBuffersпамять ArrayBuffer, SharedArrayBuffer и всех Buffer, входит в external

Данные Buffer не лежат в куче V8. В куче только маленький объект-обёртка, а байты выделены нативно. Это легко проверить:

const chunks = []
for (let i = 0; i < 50; i++) chunks.push(Buffer.alloc(10 * 1024 * 1024, 1))
console.log(process.memoryUsage())
// Node 22: heapUsed 3 МБ, external 501 МБ, arrayBuffers 500 МБ, rss 541 МБ

heapUsed не сдвинулся, а rss вырос на полгигабайта. По одной куче такую утечку не увидеть. Заполнитель 1 нужен для честного замера: обнулённые страницы ОС выдаёт лениво, и без записи rss почти не растёт. Для частых замеров одного rss есть более быстрый process.memoryUsage.rss()

📦 Лимит кучи и контейнер

Флаг --max-old-space-size задаёт в мегабайтах лимит старого поколения, а не всего процесса. Без флага Node берёт меньшее из памяти машины и ограничения ОС, а ограничение libuv на Linux читает из cgroups. Значит, cgroup-лимит контейнера Node учитывает. Дальше V8 берёт долю этого объёма с потолком около 4 ГБ на 64-битных системах, точная доля менялась между версиями V8

const v8 = require('node:v8')
console.log(v8.getHeapStatistics().heap_size_limit / 1024 / 1024)
// node app.js                            → 4144 на машине с 16 ГБ
// node --max-old-space-size=512 app.js   → 560: лимит старого поколения плюс молодое
console.log(process.constrainedMemory()) // 0, если ОС не ограничивает процесс

Флаг --max-old-space-size-percentage=N задаёт лимит процентом от доступной памяти и тоже берёт cgroup-лимит, если он есть. Он появился в Node 24.6.0 и перенесён в 22.21.0, а если указаны оба флага, побеждает процентный. В Kubernetes это удобно: поменял resources.limits.memory, и куча подстроилась сама. Про лимиты подов — на странице про пробы и ресурсы в модуле ops

Почему OOMKilled при небольшом heapUsed

Это два разных падения:

  • Куча упёрлась в свой лимит. V8 пишет FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory и прерывает процесс, код выхода 134
  • Контейнер превысил лимит памяти. Ядро убивает процесс сигналом SIGKILL без единой строки в логе, Kubernetes пишет OOMKilled и код 137. Считается вся память контейнера, а не только куча

Во втором случае heapUsed может быть 300 МБ при лимите кучи 1,5 ГБ. Растёт то, что вне кучи: Buffer из стримов и загрузок, сжатие через zlib, нативные аддоны вроде sharp или драйверов БД, стеки worker threads, фрагментация нативного аллокатора. Правило: лимит кучи должен быть заметно меньше лимита контейнера, на нативную память оставляют запас. Документация Node для машины на 2 ГиБ советует 1536 МБ под кучу

🕳️ Типовые утечки

Почти любая утечка в Node — это долгоживущий объект, который держит ссылку на то, что должно было умереть

  • Map или объект-кэш без лимита. Кладут ответы по ключу запроса и никогда не удаляют. Кэшу нужны потолок размера и TTL, например через lru-cache
  • Слушатели EventEmitter. emitter.on(...) в обработчике запроса без снятия: каждый слушатель держит своё замыкание. После десятого слушателя на одно событие Node печатает MaxListenersExceededWarning: Possible EventEmitter memory leak detected
  • Замыкание держит большой объект. Колбэк, сохранённый надолго, ссылается на переменную с целым телом запроса, хотя нужен был только id
  • Незачищенный setInterval. Таймер держит всё, что видит его колбэк, пока не вызван clearInterval. Классика: интервал на каждое WebSocket-соединение без очистки при close
  • Массив метрик или логов. Замеры копят «чтобы потом отправить», а отправка упала. Буфер должен быть ограничен

WeakMap держит ключ слабо: когда на объект-ключ больше никто не ссылается, запись уходит вместе с ним, а WeakRef позволяет держать объект и не мешать его сбору

Утечка через кэш в цифрах:

JavaScript · Кэш без лимита и рост heapUsed

const cache = new Map()
const mb = (n) => (n / 1024 / 1024).toFixed(0)
let id = 0

function handle() {
  // каждая обработка кладёт результат в кэш и никогда не удаляет
  cache.set(`req-${id++}`, new Array(1000).fill(id))
}

for (let round = 1; round <= 5; round++) {
  for (let i = 0; i < 5_000; i++) handle()
  global.gc?.()
  const m = process.memoryUsage()
  console.log(`раунд ${round}: heapUsed ${mb(m.heapUsed)} МБ, rss ${mb(m.rss)} МБ`)
}
// node --expose-gc leak.js, Node 22:
// раунд 1: heapUsed 42 МБ, rss 93 МБ
// раунд 3: heapUsed 119 МБ, rss 173 МБ
// раунд 5: heapUsed 197 МБ, rss 253 МБ

Принудительный gc() отделяет утечку от несобранного мусора: если heapUsed растёт и после полной сборки, объекты достижимы

🔍 Как искать утечку

Heap snapshot — это снимок всей кучи: каждый объект, его размер и кто на него ссылается. Снять его можно четырьмя способами:

  • запустить с --inspect, открыть chrome://inspect, вкладка Memory, кнопка снимка
  • запустить с --heapsnapshot-signal=SIGUSR2 и отправить процессу kill -USR2 <pid>
  • вызвать v8.writeHeapSnapshot() из кода, функция вернёт имя файла
  • запустить с --heapsnapshot-near-heap-limit=2, и Node сам запишет до двух снимков, когда куча подойдёт к лимиту

Главный приём — сравнение. Дай сервису прогреться, сними снимок, погоняй подозрительный сценарий несколько сотен раз, сними второй. В DevTools загрузи оба, выбери второй и переключи вид с Summary на Comparison, отсортируй по # Delta: наверху окажутся конструкторы, чьих экземпляров стало больше. У такого объекта в панели Retainers видна цепочка, которая держит его живым, например Map в модуле кэша. Там и чинить

Один снимок показывает состав кучи, но не рост. Помогает и Shallow против Retained размера: объект может весить 40 байт сам по себе, но удерживать 200 МБ через ссылки

CPU-профиль

Если сервис тормозит, снимают CPU-профиль: node --cpu-prof app.js при выходе пишет файл .cpuprofile, его открывают в DevTools или в speedscope. Там flame graph: по горизонтали доля времени, по вертикали стек вызовов. Широкие плато наверху — функции, которые сами жгут CPU. На живом процессе профиль снимают через --inspect. Как CPU-задачи блокируют цикл, разобрано на отдельной странице модуля

Clinic.js по собственному README не поддерживается активно и может врать на свежих Node, последний релиз 13.0.0 вышел в июне 2023. Для flame graph живая альтернатива — 0x, версия 6.0.0 вышла в июле 2025, но обычно хватает встроенных --cpu-prof, --heap-prof и DevTools

🚑 Диагностика в проде

Сначала метрики, потом снимки. prom-client из коробки отдаёт nodejs_heap_size_used_bytes, nodejs_heap_size_total_bytes, nodejs_external_memory_bytes и process_resident_memory_bytes. Пила heapUsed, которая возвращается к одному уровню, это норма. Если растёт минимум пилы, течёт куча. Если растёт rss при ровной куче, течёт нативная память. Как собирать и смотреть метрики, разобрано в общем модуле ops

Снимок в проде снимают с одного пода, и опасностей две. Снимок останавливает процесс: генерация синхронная, на большой куче это десятки секунд или больше минуты, и проба liveness может успеть перезапустить под. И снимку нужно примерно вдвое больше памяти, чем занимает куча, поэтому под у лимита контейнера получит OOMKilled прямо на снимке. Порядок:

  1. Выбрать один под и вывести его из балансировки
  2. Снять снимок по сигналу SIGUSR2, если процесс запущен с --heapsnapshot-signal
  3. Скопировать файл через kubectl cp и разбирать локально
  4. Повторить через час-два и сравнить

Эндпоинт /debug/heapdump наружу не выставляют: любой остановит сервис одним запросом. Снимок содержит все строки из памяти, включая токены и персональные данные, поэтому файл хранят как секрет

⚠️ Где ошибаются

  • Ставят --max-old-space-size равным лимиту контейнера. Куча доходит до лимита, нативной памяти места нет, ядро убивает процесс. Оставляй запас или используй процентный флаг
  • Делают вывод по одному снимку или без прогрева. На старте куча растёт законно: JIT, кэши модулей, пулы соединений. Сравнивать надо два снимка после прогрева

🎯 Вопросы с собеседований

Как устроена память и сборщик мусора в V8?

Куча делится на поколения, потому что большинство объектов умирает молодыми. Новые объекты выделяются в new space из двух semi-space, малая сборка scavenger копирует выживших во вторую половину, и её цена зависит от числа выживших. Пережившие две сборки уходят в old space, там работает mark-sweep-compact: маркировка от корней, очистка в списки свободных блоков и уплотнение фрагментированных страниц. Orinoco делает маркировку конкурентно в фоне, на главном потоке остаётся короткая финализация

Что показывает process.memoryUsage()?

rss — вся физическая память процесса. heapTotal и heapUsed — выделенная и занятая куча V8. external — нативная память C++-объектов, привязанных к JS, в том числе данные Buffer. arrayBuffers — память ArrayBuffer и Buffer, она входит в external. В разнице между rss и кучей прячутся утечки Buffer

Какие бывают типовые утечки в Node?

Кэш в Map без лимита и TTL, слушатели EventEmitter без снятия, замыкания, держащие большой объект ради одного поля, setInterval без clearInterval, массив метрик или логов, который никто не сбрасывает. Общий признак: долгоживущий объект держит ссылку на короткоживущий

Как найти утечку памяти в долгоживущем Node-процессе?

Сначала по метрикам понять, где рост. Если растут минимумы heapUsed после сборок, течёт куча, а если растёт только rss, течёт нативная память. Для кучи снять два heap snapshot после прогрева с нагрузкой между ними: по сигналу через --heapsnapshot-signal, через v8.writeHeapSnapshot() или --inspect. В DevTools сравнить их в режиме Comparison и по цепочке Retainers найти, кто держит лишние объекты. В проде делать это на одном поде, выведенном из балансировки, потому что снимок останавливает процесс и требует вдвое больше памяти

Что такое heap snapshot и как сравнивать снимки?

Это файл со всеми объектами кучи, их размерами и ссылками между ними. В DevTools загружают оба, на втором выбирают Comparison и сортируют по дельте, затем у растущего конструктора смотрят Retainers: цепочку от корня до объекта. Retained size показывает, сколько памяти освободится, если убрать объект вместе со всем, что держится только на нём

Почему под с Node убивает OOMKilled, хотя heapUsed далеко от лимита?

Лимит кучи ограничивает только старое поколение V8, а ядро считает всю память контейнера. Растёт то, что вне кучи: данные Buffer, zlib, нативные аддоны, стеки потоков, фрагментация аллокатора. Если бы закончилась куча, был бы JavaScript heap out of memory и код 134, а OOMKilled с кодом 137 значит, что пришло ядро. Смотреть надо на rss и external, лимит кучи держать заметно ниже лимита контейнера или задать его через --max-old-space-size-percentage

📚 Что почитать

  • Trash talk: the Orinoco garbage collector — как устроены scavenger, mark-compact и конкурентная маркировка, от авторов V8
  • Using Heap Snapshot — официальный гайд Node: способы снять снимок, сравнение, предупреждения для прода
  • process.memoryUsage() — точные определения полей
  • Command-line options — --max-old-space-size, процентный вариант, --heapsnapshot-near-heap-limit, --cpu-prof