Встроенные модули Node.js
Половина пакетов в package.json часто решает задачи, которые рантайм закрывает сам: разбор путей, чтение файлов, генерация UUID, работа с переменными окружения. Стандартная библиотека Node не требует установки, не добавляет зависимостей и обновляется вместе с рантаймом. Разберём основные модули node:*, их реальные API и ловушки, из-за которых код, на первый взгляд безопасный, роняет процесс или теряет данные.
Содержание
- Что считается встроенным модулем
- process: окружение, аргументы и выход
- Buffer: работа с бинарными данными
- path: пути без склейки строк
- fs: файлы, синхронность и промисы
- os: что процесс знает о машине
- url: разбор и сборка адресов
- crypto: случайность, хеши и сравнение
- timers: задержки и их цена
- Встроенное вместо зависимостей
- Эксперименты, которые объясняют API
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Что считается встроенным модулем
Встроенные модули — часть рантайма, а не отдельный пакет. Их не нужно устанавливать, они написаны на JavaScript и C++ и вызывают те же системные библиотеки, что и сам Node: OpenSSL для криптографии, libuv для файлов и сети, zlib для сжатия.
| Задача | Модуль |
|---|---|
| Процесс и окружение | node:process, node:os |
| Файлы и пути | node:fs, node:path |
| Бинарные данные | node:buffer |
| Сеть и HTTP | node: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.
Встроенное вместо зависимостей
Многие популярные пакеты сегодня дублируют то, что уже есть в рантайме:
| Задача | Пакет | Встроенное решение |
|---|---|---|
| UUID | uuid | crypto.randomUUID() |
.env-файл | dotenv | node --env-file=.env, process.loadEnvFile() |
| HTTP-клиент | axios, node-fetch | глобальный fetch (undici) |
| Тест-раннер | jest, mocha | node:test + node:assert |
| Перезапуск при изменениях | nodemon | node --watch |
| Base64URL | base64url | buf.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