Навигация

Встроенные модули Node.js

Половина пакетов в package.json часто решает задачи, которые рантайм закрывает сам: разбор путей, чтение файлов, генерация UUID, работа с переменными окружения. Стандартная библиотека Node не требует установки, не добавляет зависимостей и обновляется вместе с рантаймом. Разберём основные модули node:*, их реальные API и ловушки, из-за которых код, на первый взгляд безопасный, роняет процесс или теряет данные.

Содержание

  1. Что считается встроенным модулем
  2. process: окружение, аргументы и выход
  3. Buffer: работа с бинарными данными
  4. path: пути без склейки строк
  5. fs: файлы, синхронность и промисы
  6. os: что процесс знает о машине
  7. url: разбор и сборка адресов
  8. crypto: случайность, хеши и сравнение
  9. timers: задержки и их цена
  10. Встроенное вместо зависимостей
  11. Эксперименты, которые объясняют API
  12. Ключевые тезисы для интервью
  13. Заключение
  14. Полезные ссылки

Что считается встроенным модулем

Встроенные модули — часть рантайма, а не отдельный пакет. Их не нужно устанавливать, они написаны на JavaScript и C++ и вызывают те же системные библиотеки, что и сам Node: OpenSSL для криптографии, libuv для файлов и сети, zlib для сжатия.

ЗадачаМодуль
Процесс и окружениеnode:process, node:os
Файлы и путиnode:fs, node:path
Бинарные данныеnode:buffer
Сеть и HTTPnode:net, node:http, node:http2, node:dns
Адресаnode:url, node:querystring
Криптографияnode:crypto, node:tls
Времяnode:timers, node:timers/promises
Потоки и событияnode:stream, node:events
Тестыnode:test, node:assert

Префикс node: появился, чтобы импорт был однозначным: резолвер сразу понимает, что это встроенный модуль, и не ищет пакет с тем же именем в node_modules. В ESM эта форма рекомендуется, в CommonJS работает и старая: require('fs') и require('node:fs') дают одно и то же. Подробнее о форматах и разрешении имён — в статье «Модули: CommonJS и ESM».

Встроенные API не равны «простым» API: fs, crypto и stream — это обёртки над системными вызовами со своими правилами. Поэтому важно понимать, что именно уходит в ядро ОС и где проходит граница с event loop — об этом в статье «Node.js: как устроен рантайм».


process: окружение, аргументы и выход

process доступен глобально, без импорта, и описывает текущий процесс: переменные окружения, аргументы командной строки, версию Node и способ завершения.

process.env

Переменные окружения — основной способ передать конфигурацию в контейнер. Два свойства, которые нужно помнить:

  • все значения — строки или undefined. process.env.PORT — это "3000", а не число;
  • любое присваивание приводится к строке. process.env.DEBUG = false запишет "false", и проверка if (process.env.DEBUG) будет истинной.
const port = Number(process.env.PORT ?? 3000);

if (!Number.isInteger(port) || port <= 0) {
  throw new Error(`Некорректный PORT: ${process.env.PORT}`);
}

Именно поэтому конфиг валидируют на старте, а не в обработчике запроса: подробнее — в статье «Конфигурация и валидация» этого раздела.

process.argv

argv — массив аргументов, где первые два элемента служебные:

node server.mjs --port 3000 --verbose
process.argv;      // [путь к node, путь к server.mjs, '--port', '3000', '--verbose']
process.argv.slice(2); // ['--port', '3000', '--verbose']

Для разбора флагов в Node 18.3+ есть node:util с parseArgs, но для сервиса обычно достаточно переменных окружения: аргументы командной строки — удел CLI-утилит.

exitCode, exit и сигналы

СпособЧто происходит
process.exitCode = 1процесс завершится с этим кодом, когда event loop опустеет
process.exit(1)процесс завершается немедленно, не дожидаясь ввода-вывода
SIGTERM / SIGINTсигналы, которые можно перехватить и корректно завершиться
SIGKILLпринудительное убийство, перехватить нельзя

Предпочтительный вариант для ошибки — выставить exitCode и дать процессу завершиться самому: так успеют дописаться логи и закрыться соединения. process.exit() полезен в CLI, где нужно прервать работу прямо сейчас, но в сервере он может обрезать буфер stdout и оставить незакрытые транзакции.

process.on('SIGTERM', async () => {
  await new Promise((resolve) => server.close(resolve)); // новые соединения не принимаем
  await pool.end();                                      // закрываем пул БД
  process.exitCode = 0;                                  // выходим, когда event loop опустеет
});

Полноценный graceful shutdown с дренажом соединений и таймаутом — тема статьи «Таймауты, ретраи и graceful shutdown».

Ещё один инструмент — process.nextTick(): он ставит колбэк в очередь, которая разбирается до продолжения event loop, раньше промисов и таймеров. Это удобно, чтобы отложить вызов на конец текущей операции, но рекурсивный nextTick полностью блокирует цикл.


Buffer: работа с бинарными данными

Строки в JavaScript — это UTF-16 и неизменяемые последовательности символов. Файлы, сокеты и заголовки HTTP работают с байтами, поэтому Node использует Buffer.

Исторически Buffer был отдельным классом, но с Node 4 это подкласс Uint8Array: у него есть индексирование, length, subarray и остальные методы типизированных массивов, а сверху добавлены кодировки. Строка — это текст в UTF-16, буфер — байты: одна и та же строка занимает разное число байт в разных кодировках, а её length считает символы, а не байты.

import { Buffer } from 'node:buffer';

const buf = Buffer.from('hello');
console.log(buf);                    // <Buffer 68 65 6c 6c 6f>
console.log(buf.toString('hex'));    // 68656c6c6f
console.log(buf.toString('base64')); // aGVsbG8=

Buffer.byteLength('привет');         // 12 — байт, а не символов

Поддерживаемые кодировки: utf8 (по умолчанию), utf16le, latin1, ascii, base64, base64url, hex. Buffer не заменяет TextEncoder/TextDecoder, но на сервере чаще используют именно его.

alloc, allocUnsafe и пул

const safe = Buffer.alloc(1024);       // занулён, предсказуем
const fast = Buffer.allocUnsafe(1024); // не занулён, быстрее

allocUnsafe не очищает память: он выдаёт кусок из общего пула (Buffer.poolSize, 8 КиБ по умолчанию), и в нём могут лежать данные предыдущих операций. Для внутренних вычислений это нормально, но если такой буфер отправить клиенту или записать в файл, можно утечь чужие данные. Правило простое: allocUnsafe — только когда весь буфер будет перезаписан до чтения.

Общая память

subarray и slice не копируют данные, а смотрят в тот же участок памяти:

const buf = Buffer.from('hello');
const view = buf.subarray(0, 2);

view[0] = 0x48;            // код 'H'
console.log(buf.toString()); // Hello — изменился исходный буфер

Если нужен независимый кусок, используйте Buffer.from(view) — он копирует. Та же логика у Buffer.concat(): он создаёт новый буфер и копирует в него данные.

Буферы живут вне кучи V8 (external memory), поэтому в process.memoryUsage() они видны в arrayBuffers и external, а не в heapUsed. Для контейнера с лимитом памяти это не значит «бесплатно»: RSS растёт, и OOM killer срабатывает по общему потреблению процесса.


path: пути без склейки строк

Склеивать пути через '/' — классическая ошибка, которая работает на macOS и ломается на Windows, где разделитель \. Модуль path знает про платформу и нормализует результат.

import path from 'node:path';

path.join('src', 'utils', 'index.js'); // 'src/utils/index.js'
path.join('src', '..', 'dist');        // 'dist'
path.join('src', '//utils//');         // 'src/utils'

join и resolve

Разница не в косметике, а в том, от чего считается путь:

path.join('a', '/b');    // 'a/b'  — абсолютный сегмент просто приклеился
path.resolve('a', '/b'); // '/b'   — абсолютный сегмент сбросил накопленное

join собирает относительный путь и нормализует его. resolve идёт справа налево, пока не найдёт абсолютный сегмент, а если такого нет — подставляет текущую рабочую директорию:

// cwd = /home/user/app
path.resolve('dist', 'app.js');   // '/home/user/app/dist/app.js'
path.resolve('/var', 'log.txt');  // '/var/log.txt'

Практическое правило: join — чтобы собрать путь внутри известной папки, resolve — чтобы получить абсолютный путь из относительного.

Разбор и служебные значения

path.parse('/srv/app/config.json');
// { root: '/', dir: '/srv/app', base: 'config.json', ext: '.json', name: 'config' }

path.extname('archive.tar.gz'); // '.gz'
path.basename('/srv/app/server.js', '.js'); // 'server'
path.sep;                       // '/' на POSIX, '\\' на Windows

Для предсказуемого поведения независимо от ОС есть path.posix и path.win32 — явные реализации одного и того же API.

Пути и безопасность

path.join(root, userInput) не защищает от ..: пользователь может передать ../../etc/passwd, и join честно нормализует путь наружу. Перед обращением к файлу проверяют, что итоговый путь остался внутри корня:

import path from 'node:path';

function safeResolve(root, name) {
  const target = path.resolve(root, name);
  const relative = path.relative(root, target);

  if (relative.startsWith('..') || path.isAbsolute(relative)) {
    throw new Error('Путь вне разрешённого каталога');
  }
  return target;
}

Сравнение строкой через startsWith опасно: /srv/app-backup тоже начинается с /srv/app. path.relative решает задачу корректно. Подробнее про path traversal и другие атаки — в статье «Безопасность Node API».

В ESM нет __dirname, поэтому корень приложения берут из import.meta.dirname — об этом в статье «Модули: CommonJS и ESM».


fs: файлы, синхронность и промисы

Модуль node:fs существует в трёх видах:

APIИмпортКогда использовать
Колбэкиnode:fsстарый код, низкоуровневые операции
Синхронноеnode:fsстарт приложения и CLI-скрипты
Промисыnode:fs/promisesсерверный код

Синхронные методы (readFileSync, statSync) блокируют главный поток на всё время операции: пока читается файл, сервис не обрабатывает запросы. Их место — инициализация и утилиты, но не обработчики.

readFile и createReadStream

import { readFile } from 'node:fs/promises';

const config = JSON.parse(await readFile('./config.json', 'utf8'));

readFile сначала выделяет буфер под весь файл, потом читает его целиком. Для конфига в пару килобайт это идеально, для лога на гигабайт — прямой путь к OOM: файл размером больше лимита вообще не откроется (ERR_FS_FILE_TOO_LARGE). Большие файлы читают потоком через createReadStream — подробнее в статье «Стримы и backpressure».

Ошибки и атомарная запись

async function loadConfig(file) {
  try {
    return JSON.parse(await readFile(file, 'utf8'));
  } catch (err) {
    if (err.code === 'ENOENT') return {}; // файла нет — значения по умолчанию
    throw err;                            // синтаксис JSON или права — наверх
  }
}

Коды (ENOENT, EACCES, EEXIST, ENOSPC) — часть контракта: по ним различают «нет файла» и «нет прав», а не ловят всё подряд.

writeFile не атомарен: если процесс упадёт посередине, на диске останется обрезанный файл. Для файлов, которые другие процессы читают как конфиг, пишут во временный файл и подменяют его через rename в пределах той же файловой системы:

import { writeFile, rename } from 'node:fs/promises';

await writeFile(`${file}.tmp`, data);
await rename(`${file}.tmp`, file); // атомарная подмена

Ещё две ловушки:

  • fs.access не гарантирует доступ. Между проверкой и открытием файл может исчезнуть (TOCTOU). Надёжнее сразу открывать и обрабатывать ENOENT/EACCES.
  • fs.watch платформозависим. На Linux он использует inotify с лимитом подписок, на macOS даёт события по-разному, а рекурсивное наблюдение поддерживается не везде. Для сложных сценариев берут chokidar.

Эксклюзивное создание файла-блокировки делают через open с флагом wx: открытие падает с EEXIST, если файл уже существует, — это атомарная проверка, в отличие от existsSync.


os: что процесс знает о машине

node:os отвечает на вопросы о среде исполнения:

import os from 'node:os';

os.platform();             // 'linux' | 'darwin' | 'win32'
os.arch();                 // 'x64' | 'arm64'
os.hostname();             // имя машины или пода
os.tmpdir();               // каталог для временных файлов
os.EOL;                    // '\n' или '\r\n'
os.availableParallelism(); // сколько потоков реально доступно процессу

Два практических применения:

  • Временные файлы — только через path.join(os.tmpdir(), name), а не хардкодом /tmp: на Windows такого каталога нет.
  • Размер пулов и число воркеров — availableParallelism() точнее, чем os.cpus().length: он учитывает доступную процессу привязку к ядрам (CPU affinity), а не только физические ядра.

Но у этих данных есть предел доверия. В контейнере os.totalmem() и freemem() показывают память хоста, а не лимит пода; availableParallelism() может не совпасть с CPU-квотой. Настройки сервиса — число воркеров, размер пула, лимит кучи — задают конфигом и лимитами оркестратора, а os используют как подсказку по умолчанию.

os.freemem() вообще плохой индикатор для решений: на Linux свободная память занята page cache, и сервис, который «видит мало памяти», может работать совершенно нормально.


url: разбор и сборка адресов

Собирать URL конкатенацией — значит рано или поздно получить незакодированный & в параметре или потерянный сегмент пути. В Node есть глобальные URL и URLSearchParams (стандарт WHATWG), а модуль node:url добавляет утилиты вроде fileURLToPath.

const url = new URL('https://api.example.com/v1/tasks?limit=10');

url.hostname;              // 'api.example.com'
url.pathname;              // '/v1/tasks'
url.searchParams.get('limit'); // '10'

url.searchParams.set('limit', '20');
url.searchParams.append('tag', 'backend');
url.searchParams.append('tag', 'urgent');

url.toString(); // 'https://api.example.com/v1/tasks?limit=20&tag=backend&tag=urgent'

Относительные адреса

new URL(path, base) разрешает относительный путь от базы:

const base = new URL('https://api.example.com/v1/');

new URL('tasks/42', base).toString(); // '.../v1/tasks/42'
new URL('/tasks/42', base).toString(); // 'https://api.example.com/tasks/42'

Второй пример — частая причина 404: ведущий слэш отбрасывает путь базы целиком. Если база задаётся конфигом, её нормализуют так, чтобы она заканчивалась на /, и никогда не начинают относительный путь со слэша.

Кодирование

URLSearchParams кодирует значения сам: пробел превращается в +, & и = — в %26 и %3D. Вручную то же самое делают через encodeURIComponent, но с нюансом: он не кодирует /, поэтому для сегмента пути его применяют отдельно к каждому сегменту, а не ко всему pathname.

const params = new URLSearchParams({ q: 'node & stream', page: '2' });
params.toString(); // 'q=node+%26+stream&page=2'

url.parse() — устаревший API с другим поведением и известными проблемами безопасности. В новом коде его не используют, даже если он всё ещё доступен.

Для путей файловой системы URL не подходит: file:-адрес нужно конвертировать через fileURLToPath, иначе на Windows получится строка с file:/// и неправильными слэшами.


crypto: случайность, хеши и сравнение

node:crypto — обёртка над OpenSSL. Три задачи встречаются в бэкенде постоянно: токены, подписи и проверка целостности.

Случайность

import { randomUUID, randomBytes, randomInt } from 'node:crypto';

randomUUID();                        // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
randomBytes(32).toString('base64url'); // токен
randomInt(1, 7);                     // число в диапазоне [1, 7)

Math.random() для токенов, паролей и идентификаторов сессий не годится: это предсказуемый генератор, а не криптостойкий. randomUUID() даёт UUID v4, randomBytes() — любую длину энтропии, randomInt() — равномерное число без смещения.

Хеши и пароли

import { createHash, createHmac } from 'node:crypto';

createHash('sha256').update('payload').digest('hex');
createHmac('sha256', secret).update(rawBody).digest('hex');

Хеш проверяет целостность файла или кеш-ключа, HMAC подтверждает подпись вебхука. Хеш не подходит для паролей: SHA-256 считается слишком быстро, поэтому перебор дешёвый. Пароли хранят через scrypt (встроен в Node) или argon2 (пакет), с солью и параметрами стоимости — детали в статье «Аутентификация в API».

Сравнение за постоянное время

import { timingSafeEqual, createHmac } from 'node:crypto';

const expected = createHmac('sha256', secret).update(rawBody).digest();
const received = Buffer.from(signature, 'hex');

if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
  throw new Error('Неверная подпись');
}

=== для строк и буферов выходит на первом несовпавшем байте: атакующий может измерять время ответа и подбирать секрет по одному символу. timingSafeEqual сравнивает за постоянное время и бросает исключение, если длины буферов разные, — поэтому длину проверяют заранее. Сравнивать имеет смысл хеши или HMAC фиксированной длины, а не секреты разной длины.

Асинхронные scrypt и pbkdf2 выполняются в пуле libuv, а их синхронные версии блокируют главный поток — почему это важно, разобрано в статье «Node.js: как устроен рантайм».


timers: задержки и их цена

setTimeout и setInterval — не «таймеры реального времени», а договорённость с event loop: колбэк выполнят не раньше указанного срока, но когда цикл до него дойдёт. setImmediate устроен иначе — он срабатывает в check-фазе сразу после poll, без задержки.

setTimeout(() => console.log('не раньше 100 мс'), 100);

Задержка может быть больше на десятки и сотни миллисекунд: синхронный обработчик, тяжёлый JSON или ожидание I/O задерживают переход к фазе timers. Гарантируется только нижняя граница, а setTimeout(fn, 0) всё равно проходит через цикл и не выполняется в тот же тик. Порядок относительно setImmediate и промисов зависит от контекста и разобран в статье «Event loop в Node.js».

ref, unref и завершение процесса

Обычный таймер держит процесс живым: Node не завершится, пока есть запланированная работа. unref() снимает этот учёт — удобно для периодической очистки, которая не должна мешать остановке:

const interval = setInterval(cleanup, 60_000);
interval.unref(); // процесс может завершиться, не дожидаясь следующего тика

Обратное — ref() — возвращает таймер в учёт. У setInterval есть ещё одна ловушка: если колбэк асинхронный, интервал не ждёт его завершения и запускает следующий вызов по расписанию. Долгая операция приводит к наложению обработчиков; вместо этого используют рекурсивный setTimeout после завершения работы.

timers/promises

Для асинхронного кода удобнее промис-версия:

import { setTimeout as sleep } from 'node:timers/promises';

await sleep(100, undefined, { signal: controller.signal });

Она поддерживает AbortSignal и не требует оборачивать setTimeout в new Promise. Но sleep в обработчике запроса — почти всегда плохой сигнал: ожидание ресурса лучше заменить событием или повтором с backoff.


Встроенное вместо зависимостей

Многие популярные пакеты сегодня дублируют то, что уже есть в рантайме:

ЗадачаПакетВстроенное решение
UUIDuuidcrypto.randomUUID()
.env-файлdotenvnode --env-file=.env, process.loadEnvFile()
HTTP-клиентaxios, node-fetchглобальный fetch (undici)
Тест-раннерjest, mochanode:test + node:assert
Перезапуск при измененияхnodemonnode --watch
Base64URLbase64urlbuf.toString('base64url')

Это не значит, что библиотеки не нужны. fetch не умеет ретраи и хуки, node:test минималистичен, --env-file не валидирует схему. Решение принимают по разнице в возможностях, а не по привычке: каждая зависимость — это обновления, уязвимости и вес установки.

Отдельный аргумент — supply chain. Пакет с миллионами скачиваний может быть скомпрометирован или унаследовать уязвимость из транзитивных зависимостей. Встроенный модуль обновляется вместе с Node и не тянет чужой код.

У --env-file есть важная деталь: переменные, уже заданные в окружении, имеют приоритет над файлом. Это удобно в контейнере — файл даёт значения по умолчанию, а оркестратор переопределяет нужные.


Эксперименты, которые объясняют API

Три коротких опыта, которые показывают поведение лучше документации.

1. Buffer делит память

const buf = Buffer.from('hello');
const view = buf.subarray(0, 2);
view[0] = 0x48;

console.log(buf.toString()); // Hello

Если ожидали hello, значит представление «subarray — независимая копия» ещё не сформировалось. Изменение затронуло исходный буфер.

2. join и resolve ведут себя по-разному

import path from 'node:path';

console.log(path.join('src', '/etc', 'passwd'));   // src/etc/passwd
console.log(path.resolve('src', '/etc', 'passwd')); // /etc/passwd

Первый вариант остался относительным, второй ушёл в абсолютный путь. Этот же опыт показывает, почему пользовательский ввод нельзя бездумно передавать в resolve без проверки корня.

3. Переменная окружения всегда строка

DEBUG=false node -e "console.log(Boolean(process.env.DEBUG))"
# true

Строка "false" истинна. Любая проверка флага требует явного разбора, а не приведения через Boolean.


Ключевые тезисы для интервью

  • Встроенные модули — часть рантайма: префикс node: делает импорт однозначным, не требует установки и обновляется вместе с Node, но API у них такие же системные, как у обычных библиотек.
  • process — граница с ОС: env всегда строки, argv начинается со служебных элементов, exitCode завершает мягко, exit() обрывает ввод-вывод, а SIGTERM — штатный сигнал для graceful shutdown.
  • Buffer — изменяемый подкласс Uint8Array для байтов: alloc зануляет, allocUnsafe быстрее и может содержать чужие данные, а subarray делит память с исходным буфером.
  • path.join собирает относительный путь, path.resolve — абсолютный; ручная проверка startsWith не защищает от path traversal, нужен path.relative.
  • fs синхронный блокирует поток, readFile грузит файл целиком, а createReadStream и атомарная запись через rename — обязательные инструменты для больших файлов и конфигов.
  • Криптография начинается с randomBytes/randomUUID, а не Math.random; хеш — для целостности, scrypt/argon2 — для паролей, timingSafeEqual — для сравнения секретов.
  • Задержка таймера — нижняя граница, а не обещание: unref() снимает удержание процесса, setInterval не ждёт асинхронный колбэк, а timers/promises даёт отмену через AbortSignal.

Заключение

Встроенные модули покрывают базовый слой любого сервиса: процесс и окружение, файлы и пути, байты, адреса, криптографию и время. Их API кажутся простыми, но почти каждый содержит ловушку: строка "false" в process.env, subarray, меняющий исходный буфер, join, который не защищает от .., и readFile, загружающий файл целиком в память. Знание этих деталей позволяет писать меньше кода, не тянуть лишние зависимости и не терять данные при завершении процесса. Начинать стоит со стандартной библиотеки, а пакет подключать тогда, когда встроенного решения действительно не хватает.

Полезные ссылки

  • Node.js API — полный справочник встроенных модулей
  • Buffer — кодировки, alloc/allocUnsafe, пул
  • File system — fs, fs/promises, флаги и ошибки
  • Path — join, resolve, parse, posix/win32
  • Crypto — хеши, HMAC, randomUUID, timingSafeEqual
  • WHATWG URL — URL, URLSearchParams, fileURLToPath