Процесс

Объект process предоставляет информацию о текущем процессе Node.js и управление им.

import process from 'node:process';

const process = require('node:process');

События процесса

Объект process является экземпляром EventEmitter.

Событие: 'beforeExit'

Событие 'beforeExit' генерируется, когда Node.js опустошает свой цикл событий и у него нет дополнительной работы для планирования. Обычно процесс Node.js завершается, когда запланированной работы нет, но слушатель, зарегистрированный на событие 'beforeExit', может совершать асинхронные вызовы и тем самым заставлять процесс Node.js продолжать работу.

Функция обратного вызова слушателя вызывается со значением process.exitCode, переданным в качестве единственного аргумента.

Событие 'beforeExit' не генерируется при условиях, вызывающих явное завершение, таких как вызов process.exit() или необработанные исключения.

Событие 'beforeExit' не следует использовать в качестве альтернативы событию 'exit', за исключением случаев, когда целью является планирование дополнительной работы.

import process from 'node:process';

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0

Событие: 'disconnect'

Если процесс Node.js запущен с каналом IPC (см. документацию по Child Process и Cluster), событие 'disconnect' будет сгенерировано при закрытии канала IPC.

Событие: 'exit'

• code <integer>

Событие 'exit' генерируется, когда процесс Node.js готов к завершению в результате одного из следующих событий:

• Явного вызова метода process.exit();
• Отсутствия у цикла событий Node.js какой-либо дополнительной работы для выполнения.

На этом этапе предотвратить выход из цикла событий невозможно, и как только все слушатели 'exit' завершат работу, процесс Node.js завершится.

Функция обратного вызова слушателя вызывается с кодом завершения, указанным либо в свойстве process.exitCode, либо в аргументе exitCode, переданном методу process.exit().

import process from 'node:process';

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});

Функции-слушатели должны выполнять только синхронные операции. Процесс Node.js завершится сразу после вызова слушателей события 'exit', в результате чего любая дополнительная работа, все еще находящаяся в очереди цикла событий, будет отброшена. Например, в следующем примере тайм-аут никогда не сработает:

import process from 'node:process';

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});

Событие: 'message'

• message <Object> | <boolean> | <number> | <string> | <null> распарсенный JSON-объект или сериализуемое примитивное значение.
• sendHandle <net.Server> | <net.Socket> объект net.Server или net.Socket, или undefined.

Если процесс Node.js запущен с каналом IPC (см. документацию по Child Process и Cluster), событие 'message' генерируется всякий раз, когда дочерний процесс получает сообщение, отправленное родительским процессом с помощью childprocess.send().

Сообщение проходит через сериализацию и парсинг. Результирующее сообщение может отличаться от изначально отправленного.

Если при порождении процесса параметр serialization был установлен в advanced, аргумент message может содержать данные, которые невозможно представить в JSON. Дополнительные сведения см. в разделе Расширенная сериализация для child_process.

Событие: 'rejectionHandled'

• promise <Promise> Поздно обработанный промис.

Событие 'rejectionHandled' генерируется всякий раз, когда промис Promise был отклонен и обработчик ошибок был прикреплен к нему (например, с помощью promise.catch()) позже, чем через один оборот цикла событий Node.js.

Объект Promise ранее был бы передан в событии 'unhandledRejection', но в процессе обработки получил обработчик отклонения.

В цепочке Promise нет понятия верхнего уровня, на котором отклонения всегда могут быть обработаны. Будучи асинхронным по своей природе, отклонение Promise может быть обработано в будущем, возможно, намного позже оборота цикла событий, необходимого для генерации события 'unhandledRejection'.

Иными словами, в отличие от синхронного кода, где существует постоянно растущий список необработанных исключений, в промисах может существовать как растущий, так и уменьшающийся список необработанных отклонений.

В синхронном коде событие 'uncaughtException' генерируется при росте списка необработанных исключений.

В асинхронном коде событие 'unhandledRejection' генерируется при росте списка необработанных отклонений, а событие 'rejectionHandled' генерируется при его уменьшении.

import process from 'node:process';

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});

В этом примере unhandledRejections Map со временем будет расти и уменьшаться, отражая отклонения, которые сначала были необработанными, а затем были обработаны. Такие ошибки можно записывать в журнал ошибок либо периодически (что, вероятно, лучше всего подходит для долго работающих приложений), либо при завершении процесса (что, вероятно, удобнее всего для скриптов).

Событие: 'workerMessage'

• value <any> Значение, переданное с помощью postMessageToThread().
• source <number> Идентификатор передающего потока-воркера или 0 для главного потока.

Событие 'workerMessage' генерируется для любого входящего сообщения, отправленного другой стороной с помощью postMessageToThread().

Событие: 'uncaughtException'

• err <Error> Неперехваченное исключение.
• origin <string> Указывает, возникло ли исключение из-за необработанного отклонения или синхронной ошибки. Может принимать значения 'uncaughtException' или 'unhandledRejection'. Последнее используется, когда исключение возникает в асинхронном контексте на основе Promise (или если Promise отклонен), а флаг --unhandled-rejections установлен в strict или throw (по умолчанию), и отклонение не обработано, либо когда отклонение происходит на этапе статической загрузки ES-модулей точки входа командной строки.

Событие 'uncaughtException' генерируется, когда неперехваченное исключение JavaScript всплывает обратно до самого цикла событий. По умолчанию Node.js обрабатывает такие исключения путем вывода трассировки стека в stderr и завершения с кодом 1, переопределяя ранее установленный process.exitCode. Добавление обработчика для события 'uncaughtException' переопределяет это поведение по умолчанию. В качестве альтернативы можно изменить process.exitCode в обработчике 'uncaughtException', что приведет к завершению процесса с указанным кодом завершения. В противном случае при наличии такого обработчика процесс завершится с кодом 0.

import process from 'node:process';
import fs from 'node:fs';

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}\n`,
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');

const fs = require('node:fs');

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}\n`,
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');

Можно отслеживать события 'uncaughtException' без переопределения стандартного поведения по завершению процесса, установив слушатель 'uncaughtExceptionMonitor'.

Предупреждение: корректное использование 'uncaughtException'

'uncaughtException' — это грубый механизм обработки исключений, предназначенный только для крайних случаев. Это событие не следует использовать как эквивалент On Error Resume Next. Необработанные исключения по своей сути означают, что приложение находится в неопределенном состоянии. Попытка возобновить выполнение кода приложения без надлежащего восстановления после исключения может вызвать дополнительные непредвиденные и непредсказуемые проблемы.

Исключения, выброшенные из обработчика событий, перехвачены не будут. Вместо этого процесс завершится с ненулевым кодом завершения и будет выведена трассировка стека. Это сделано во избежание бесконечной рекурсии.

Попытка продолжить нормальную работу после неперехваченного исключения похожа на выдергивание шнура питания из розетки во время обновления компьютера. Девять раз из десяти ничего не произойдет. Но на десятый раз система будет повреждена.

Корректное использование 'uncaughtException' заключается в выполнении синхронной очистки выделенных ресурсов (например, файловых дескрипторов, хэндлов и т. д.) перед завершением процесса. Возобновлять нормальную работу после 'uncaughtException' небезопасно.

Чтобы перезапускать аварийно завершившееся приложение более надежным способом, независимо от того, генерируется ли 'uncaughtException' или нет, в отдельном процессе следует использовать внешний монитор для обнаружения сбоев приложения и восстановления или перезапуска по мере необходимости.

Событие: 'uncaughtExceptionMonitor'

• err <Error> Неперехваченное исключение.
• origin <string> Указывает, возникло ли исключение из-за необработанного отклонения или синхронных ошибок. Может принимать значения 'uncaughtException' или 'unhandledRejection'. Последнее используется, когда исключение возникает в асинхронном контексте на основе Promise (или если Promise отклонен), а флаг --unhandled-rejections установлен в strict или throw (по умолчанию), и отклонение не обработано, либо когда отклонение происходит на этапе статической загрузки ES-модулей точки входа командной строки.

Событие 'uncaughtExceptionMonitor' генерируется до того, как сгенерируется событие 'uncaughtException' или будет вызван хук, установленный с помощью process.setUncaughtExceptionCaptureCallback().

Установка слушателя 'uncaughtExceptionMonitor' не меняет поведение при генерации события 'uncaughtException'. Процесс по-прежнему завершится с ошибкой, если не установлен слушатель 'uncaughtException'.

import process from 'node:process';

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.js

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.js

Событие: 'unhandledRejection'

• reason <Error> | <any> Объект, с которым промис был отклонен (обычно объект Error).
• promise <Promise> Отклоненный промис.

Событие 'unhandledRejection' генерируется всякий раз, когда Promise отклоняется и к промису не прикреплен обработчик ошибок в течение одного оборота цикла событий. При программировании с использованием промисов исключения инкапсулируются как «отклоненные промисы». Отклонения можно перехватывать и обрабатывать с помощью promise.catch(), и они распространяются по цепочке Promise. Событие 'unhandledRejection' полезно для обнаружения и отслеживания отклоненных промисов, отклонения которых еще не были обработаны.

import process from 'node:process';

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`

Следующий код также вызовет генерацию события 'unhandledRejection':

import process from 'node:process';

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turn

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turn

В данном примере отклонение можно отслеживать как ошибку разработчика, как это обычно происходит для других событий 'unhandledRejection'. Чтобы устранить подобные сбои, к resource.loaded можно прикрепить пустой обработчик .catch(() => { }), что предотвратит генерацию события 'unhandledRejection'.

Если событие 'unhandledRejection' сгенерировано, но не обработано, оно вызовет неперехваченное исключение. Это, наряду с другим поведением событий 'unhandledRejection', можно изменить с помощью флага --unhandled-rejections.

Событие: 'warning'

• warning <Error> Ключевые свойства предупреждения:
  • name <string> Имя предупреждения. По умолчанию: 'Warning'.
  • message <string> Предоставленное системой описание предупреждения.
  • stack <string> Трассировка стека до места в коде, где было выдано предупреждение.

Событие 'warning' генерируется всякий раз, когда Node.js выдает предупреждение процесса.

Предупреждение процесса похоже на ошибку тем, что описывает исключительные условия, на которые обращается внимание пользователя. Однако предупреждения не являются частью стандартного потока обработки ошибок Node.js и JavaScript. Node.js может выдавать предупреждения всякий раз, когда обнаруживает неоптимальные практики написания кода, которые могут привести к ухудшению производительности приложения, багам или уязвимостям безопасности.

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});

По умолчанию Node.js выводит предупреждения процесса в stderr. Параметр командной строки --no-warnings можно использовать для подавления стандартного вывода в консоль, но событие 'warning' все равно будет генерироваться объектом process. В настоящее время невозможно подавлять определенные типы предупреждений, кроме предупреждений об устаревании. Сведения о том, как скрыть предупреждения об устаревании, см. в описании флага --no-deprecation.

В следующем примере показано предупреждение, которое выводится в stderr, когда на событие добавлено слишком много слушателей:

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leak
detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit
consolecopy

В отличие от этого, в следующем примере отключается стандартный вывод предупреждений и добавляется пользовательский обработчик для события 'warning':

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Do not do that!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Do not do that!
consolecopy

Параметр командной строки --trace-warnings можно использовать для того, чтобы стандартный вывод предупреждений в консоль включал полную трассировку стека предупреждения.

Запуск Node.js с флагом командной строки --throw-deprecation приведет к тому, что пользовательские предупреждения об устаревании будут выбрасываться как исключения.

Использование флага командной строки --trace-deprecation приведет к выводу пользовательского предупреждения об устаревании в stderr вместе с трассировкой стека.

Использование флага командной строки --no-deprecation подавит все сообщения о пользовательском устаревании.

Флаги командной строки *-deprecation влияют только на предупреждения, использующие имя 'DeprecationWarning'.

Генерация пользовательских предупреждений

Сведения о выдаче пользовательских или специфичных для приложения предупреждений см. в описании метода process.emitWarning().

Имена предупреждений Node.js

Строгих правил для типов предупреждений (определяемых свойством name), генерируемых Node.js, не существует. Новые типы предупреждений могут быть добавлены в любое время. Среди наиболее распространенных типов предупреждений можно выделить следующие:

• 'DeprecationWarning' — указывает на использование устаревшего API или функционала Node.js. Такие предупреждения должны содержать свойство 'code', определяющее код устаревания.
• 'ExperimentalWarning' — указывает на использование экспериментального API или функционала Node.js. Такие функции следует использовать с осторожностью, поскольку они могут измениться в любое время и не подпадают под действие тех же строгих правил семантического версионирования и долгосрочной поддержки, что и поддерживаемые возможности.
• 'MaxListenersExceededWarning' — указывает на то, что для данного события зарегистрировано слишком много слушателей на EventEmitter или EventTarget. Часто это признак утечки памяти.
• 'TimeoutOverflowWarning' — указывает на то, что функции setTimeout() или setInterval() было передано числовое значение, которое не помещается в 32-битное знаковое целое число.
• 'TimeoutNegativeWarning' — указывает на то, что функции setTimeout() или setInterval() было передано отрицательное число.
• 'TimeoutNaNWarning' — указывает на то, что функции setTimeout() или setInterval() было передано значение, не являющееся числом.
• 'UnsupportedWarning' — указывает на использование неподдерживаемой опции или функции, которая будет проигнорирована, а не обработана как ошибка. Одним из примеров является использование сообщения о статусе HTTP-ответа при использовании API совместимости с HTTP/2.

Событие: 'worker'

• worker <Worker> Созданный объект <Worker>.

Событие 'worker' генерируется после создания нового потока <Worker>.

События сигналов

События сигналов генерируются при получении процессом Node.js сигнала. Список стандартных имен сигналов POSIX, таких как 'SIGINT', 'SIGHUP' и т. д., приведен в signal(7).

Сигналы недоступны в потоках Worker.

Обработчик сигнала получает имя сигнала ('SIGINT', 'SIGTERM' и т. д.) в качестве первого аргумента.

Имя каждого события будет общепринятым именем сигнала в верхнем регистре (например, 'SIGINT' для сигналов SIGINT).

import process from 'node:process';

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);

• 'SIGUSR1' зарезервирован Node.js для запуска отладчика. Установить слушатель возможно, но это может помешать работе отладчика.
• 'SIGTERM' и 'SIGINT' имеют стандартные обработчики на платформах, отличных от Windows, которые сбрасывают режим терминала перед завершением работы с кодом 128 + signal number. Если для одного из этих сигналов установлен слушатель, его стандартное поведение будет отключено (Node.js больше не будет завершать работу).
• 'SIGPIPE' по умолчанию игнорируется. Для него можно установить слушатель.
• 'SIGHUP' генерируется в Windows при закрытии окна консоли, а на других платформах — при различных аналогичных условиях. См. signal(7). Для него можно установить слушатель, однако примерно через 10 секунд Node.js будет безусловно завершен Windows. На платформах, отличных от Windows, стандартное поведение SIGHUP заключается в завершении Node.js, но после установки слушателя его стандартное поведение будет отключено.
• 'SIGTERM' не поддерживается в Windows; его можно прослушивать.
• 'SIGINT' из терминала поддерживается на всех платформах и обычно может быть сгенерирован с помощью Ctrl+C (хотя это можно настроить). Он не генерируется, если включен необработанный режим терминала и используется сочетание Ctrl+C.
• 'SIGBREAK' доставляется в Windows при нажатии Ctrl+Break. На платформах, отличных от Windows, его можно прослушивать, но нет способа отправить или сгенерировать его.
• 'SIGWINCH' доставляется при изменении размера консоли. В Windows это происходит только при записи в консоль при перемещении курсора или при использовании читаемого tty в необработанном (raw) режиме.
• Для 'SIGKILL' нельзя установить слушатель, он безоговорочно завершит работу Node.js на всех платформах.
• Для 'SIGSTOP' нельзя установить слушатель.
• 'SIGBUS', 'SIGFPE', 'SIGSEGV' и 'SIGILL', если они не были вызваны искусственно с помощью kill(2), по своей природе оставляют процесс в состоянии, из которого небезопасно вызывать JS-слушатели. Это может привести к тому, что процесс перестанет отвечать.
• 0 можно отправить для проверки существования процесса; он не имеет никакого эффекта, если процесс существует, но выбросит ошибку, если процесс не существует.

Windows не поддерживает сигналы и не имеет эквивалента завершению по сигналу, но Node.js предлагает некоторую эмуляцию с помощью process.kill() и subprocess.kill():

• Отправка SIGINT, SIGTERM и SIGKILL приведет к безусловному завершению целевого процесса, после чего подпроцесс сообщит, что процесс был завершен по сигналу.
• Отправку сигнала 0 можно использовать как платформонезависимый способ проверки существования процесса.

process.abort()

Метод process.abort() приводит к немедленному завершению процесса Node.js и созданию core-файла.

Эта функция недоступна в потоках Worker.

process.addUncaughtExceptionCaptureCallback(fn)

• fn <Function>

Функция process.addUncaughtExceptionCaptureCallback() добавляет обратный вызов, который будет вызван при возникновении неперехваченного исключения, получая значение исключения в качестве первого аргумента.

В отличие от process.setUncaughtExceptionCaptureCallback(), эта функция позволяет регистрировать несколько функций обратного вызова и не конфликтует с модулем domain. Обратные вызовы вызываются в порядке, обратном порядку регистрации (последний зарегистрированный — первым). Если обратный вызов возвращает true, последующие обратные вызовы и стандартная обработка неперехваченных исключений пропускаются.

import process from 'node:process';

process.addUncaughtExceptionCaptureCallback((err) => {
  console.error('Caught exception:', err.message);
  return true; // Indicates exception was handled
});

process.addUncaughtExceptionCaptureCallback((err) => {
  console.error('Caught exception:', err.message);
  return true; // Indicates exception was handled
});

process.allowedNodeEnvironmentFlags

• Тип: <Set>

Свойство process.allowedNodeEnvironmentFlags представляет собой специальный, доступный только для чтения Set флагов, допустимых в переменной окружения NODE_OPTIONS.

process.allowedNodeEnvironmentFlags расширяет Set, но переопределяет Set.prototype.has для распознавания нескольких различных вариантов представления флагов. process.allowedNodeEnvironmentFlags.has() вернёт true в следующих случаях:

• Флаги могут опускать начальные одинарные (-) или двойные (--) дефисы; например, inspect-brk вместо --inspect-brk или r вместо -r.
• В флагах, передаваемых в V8 (как указано в --v8-options), один или несколько не начальных дефисов могут быть заменены на знак подчёркивания или наоборот; например, --perf_basic_prof, --perf-basic-prof, --perf_basic-prof и т. д.
• Флаги могут содержать один или несколько символов знака равенства (=); все символы после первого знака равенства (включая его самого) будут проигнорированы; например, --stack-trace-limit=100.
• Флаги должны быть допустимыми в NODE_OPTIONS.

При итерации по process.allowedNodeEnvironmentFlags флаги будут встречаться только один раз; каждый из них будет начинаться с одного или нескольких дефисов. Флаги, передаваемые в V8, будут содержать знаки подчёркивания вместо не начальных дефисов:

import { allowedNodeEnvironmentFlags } from 'node:process';

allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});

const { allowedNodeEnvironmentFlags } = require('node:process');

allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});

Методы add(), clear() и delete() объекта process.allowedNodeEnvironmentFlags ничего не делают и молча завершаются без ошибки.

Если Node.js был скомпилирован без поддержки NODE_OPTIONS (что отражено в process.config), process.allowedNodeEnvironmentFlags будет содержать то, что было бы допустимо.

process.arch

• Тип: <string>

Архитектура процессора операционной системы, для которой был скомпилирован бинарный файл Node.js. Возможные значения: 'arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc64', 'riscv64', 's390', 's390x' и 'x64'.

import { arch } from 'node:process';

console.log(`This processor architecture is ${arch}`);

const { arch } = require('node:process');

console.log(`This processor architecture is ${arch}`);

process.argv

• Тип: <string[]>

Свойство process.argv возвращает массив, содержащий аргументы командной строки, переданные при запуске процесса Node.js. Первым элементом будет process.execPath. См. process.argv0, если требуется доступ к исходному значению argv[0]. Если была указана точка входа программы, вторым элементом будет абсолютный путь к ней. Остальные элементы представляют собой дополнительные аргументы командной строки.

Например, предположим следующий скрипт для process-args.js:

import { argv } from 'node:process';

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});

const { argv } = require('node:process');

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});

Запуск процесса Node.js следующим образом:

node process-args.js one two=three four
bashcopy

Сгенерирует следующий вывод:

0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four
textcopy

process.argv0

• Тип: <string>

Свойство process.argv0 сохраняет доступную только для чтения копию исходного значения argv[0], переданного при запуске Node.js.

$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0'
consolecopy

process.availableMemory()

• Возвращает: <number>

Получает объём свободной памяти, всё ещё доступной процессу (в байтах).

Дополнительную информацию см. в uv_get_available_memory.

process.channel

• Тип: <Object>

Если процесс Node.js был создан с IPC-каналом (см. документацию по дочерним процессам (Child Process)), свойство process.channel является ссылкой на этот IPC-канал. Если IPC-канал отсутствует, это свойство имеет значение undefined.

process.channel.ref()

Этот метод заставляет IPC-канал поддерживать цикл событий процесса в активном состоянии, если ранее был вызван метод .unref().

Как правило, это контролируется количеством слушателей 'disconnect' и 'message' на объекте process. Однако этот метод можно использовать для явного указания желаемого поведения.

process.channel.unref()

Этот метод приводит к тому, что IPC-канал не удерживает цикл событий процесса запущенным, и позволяет ему завершиться даже при открытом канале.

Как правило, это контролируется количеством слушателей 'disconnect' и 'message' на объекте process. Однако этот метод можно использовать для явного указания желаемого поведения.

process.chdir(directory)

• directory <string>

Метод process.chdir() изменяет текущий рабочий каталог процесса Node.js или вызывает исключение, если операция не удалась (например, если указанный directory не существует).

import { chdir, cwd } from 'node:process';

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

const { chdir, cwd } = require('node:process');

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

Эта функциональность недоступна в потоках Worker.

process.config

• Тип: <Object>

Свойство process.config возвращает замороженный Object, содержащий представление на JavaScript параметров конфигурации, использованных при сборке текущего исполняемого файла Node.js. Это то же самое, что и файл config.gypi, созданный при выполнении скрипта ./configure.

Пример возможного вывода выглядит следующим образом:

{
  "target_defaults":
   { "cflags": [],
     "default_configuration": "Release",
     "defines": [],
     "include_dirs": [],
     "libraries": [] },
  "variables":
   {
     "host_arch": "x64",
     "napi_build_version": 5,
     "node_install_npm": "true",
     "node_prefix": "",
     "node_shared_cares": "false",
     "node_shared_http_parser": "false",
     "node_shared_libuv": "false",
     "node_shared_zlib": "false",
     "node_use_openssl": "true",
     "node_shared_openssl": "false",
     "target_arch": "x64",
     "v8_use_snapshot": 1
   }
}
jsoncopy

process.connected

• Тип: <boolean>

Если процесс Node.js создан с IPC-каналом (см. документацию по Child Process и Cluster), свойство process.connected будет возвращать true до тех пор, пока IPC-канал подключён, и вернёт false после вызова process.disconnect().

Как только значение process.connected становится false, отправка сообщений через IPC-канал с помощью process.send() становится невозможной.

process.constrainedMemory()

• Возвращает: <number>

Получает объём памяти, доступной процессу (в байтах), с учётом ограничений, наложенных ОС. Если таких ограничений нет или ограничение неизвестно, возвращается 0.

Дополнительную информацию см. в uv_get_constrained_memory.

process.cpuUsage([previousValue])

• previousValue <Object> Предыдущее возвращённое значение от вызова process.cpuUsage()
• Возвращает: <Object>
  • user <integer>
  • system <integer>

Метод process.cpuUsage() возвращает процессорное время текущего процесса в пользовательском и системном режимах в виде объекта со свойствами user и system, значениями которых являются микросекунды (миллионные доли секунды). Эти значения измеряют время, затраченное на выполнение пользовательского и системного кода соответственно, и могут превышать фактически прошедшее астрономическое время, если над выполнением данного процесса задействовано несколько ядер процессора.

Результат предыдущего вызова process.cpuUsage() может быть передан функции в качестве аргумента для получения дифференциального значения.

import { cpuUsage } from 'node:process';

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }

const { cpuUsage } = require('node:process');

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }

process.cwd()

• Возвращает: <string>

Метод process.cwd() возвращает текущий рабочий каталог процесса Node.js.

import { cwd } from 'node:process';

console.log(`Current directory: ${cwd()}`);

const { cwd } = require('node:process');

console.log(`Current directory: ${cwd()}`);

process.debugPort

• Тип: <number>

Порт, используемый отладчиком Node.js при его активации.

import process from 'node:process';

process.debugPort = 5858;

process.debugPort = 5858;

process.disconnect()

Если процесс Node.js создан с IPC-каналом (см. документацию по Child Process и Cluster), метод process.disconnect() закроет IPC-канал к родительскому процессу, позволяя дочернему процессу корректно завершить работу, когда больше не останется других удерживающих его соединений.

Эффект от вызова process.disconnect() аналогичен вызову ChildProcess.disconnect() из родительского процесса.

Если процесс Node.js был создан без IPC-канала, process.disconnect() будет иметь значение undefined.

process.dlopen(module, filename[, flags])

• module <Object>
• filename <string>
• flags <os.constants.dlopen> По умолчанию: os.constants.dlopen.RTLD_LAZY

Метод process.dlopen() позволяет динамически загружать разделяемые объекты. В основном он используется require() для загрузки аддонов C++ и не должен использоваться напрямую, за исключением особых случаев. Другими словами, следует предпочитать require() вместо process.dlopen(), если нет особых причин, таких как пользовательские флаги dlopen или загрузка из модулей ES.

Аргумент flags — это целое число, позволяющее настроить поведение dlopen. Подробности см. в документации os.constants.dlopen.

Важным требованием при вызове process.dlopen() является передача экземпляра module. Экспортируемые аддоном C++ функции затем доступны через module.exports.

В приведённом ниже примере показано, как загрузить аддон C++ с именем local.node, экспортирующий функцию foo. Все символы загружаются до возврата из функции благодаря передаче константы RTLD_NOW. Предполагается, что в этом примере константа доступна.

import { dlopen } from 'node:process';
import { constants } from 'node:os';
import { fileURLToPath } from 'node:url';

const module = { exports: {} };
dlopen(module, fileURLToPath(new URL('local.node', import.meta.url)),
       constants.dlopen.RTLD_NOW);
module.exports.foo();

const { dlopen } = require('node:process');
const { constants } = require('node:os');
const { join } = require('node:path');

const module = { exports: {} };
dlopen(module, join(__dirname, 'local.node'), constants.dlopen.RTLD_NOW);
module.exports.foo();

process.emitWarning(warning[, options])

• warning <string> | <Error> Предупреждение, которое необходимо сгенерировать.
• options <Object>
  • type <string> Если warning является String, type — это имя, используемое для типа генерируемого предупреждения. По умолчанию: 'Warning'.
  • code <string> Уникальный идентификатор генерируемого экземпляра предупреждения.
  • ctor <Function> Если warning является String, ctor — это необязательная функция, используемая для ограничения генерируемого стека вызовов. По умолчанию: process.emitWarning.
  • detail <string> Дополнительный текст, включаемый в ошибку.

Метод process.emitWarning() может использоваться для генерации пользовательских или специфичных для приложения предупреждений процесса. Их можно перехватывать, добавив обработчик к событию 'warning'.

import { emitWarning } from 'node:process';

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information

const { emitWarning } = require('node:process');

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information

В этом примере объект Error создаётся внутри метода process.emitWarning() и передаётся в обработчик 'warning'.

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});

Если аргумент warning передан как объект Error, аргумент options игнорируется.

process.emitWarning(warning[, type[, code]][, ctor])

• warning <string> | <Error> Предупреждение, которое необходимо сгенерировать.
• type <string> Если warning является String, type — это имя, используемое для типа генерируемого предупреждения. По умолчанию: 'Warning'.
• code <string> Уникальный идентификатор генерируемого экземпляра предупреждения.
• ctor <Function> Если warning является String, ctor — это необязательная функция, используемая для ограничения генерируемого стека вызовов. По умолчанию: process.emitWarning.

Метод process.emitWarning() может использоваться для генерации пользовательских или специфичных для приложения предупреждений процесса. Их можно перехватывать, добавив обработчик к событию 'warning'.

import { emitWarning } from 'node:process';

// Emit a warning using a string.
emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!

const { emitWarning } = require('node:process');

// Emit a warning using a string.
emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!

import { emitWarning } from 'node:process';

// Emit a warning using a string and a type.
emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!

const { emitWarning } = require('node:process');

// Emit a warning using a string and a type.
emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!

import { emitWarning } from 'node:process';

emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

const { emitWarning } = require('node:process');

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

В каждом из предыдущих примеров объект Error создаётся внутри метода process.emitWarning() и передаётся в обработчик 'warning'.

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});

Если warning передан как объект Error, он будет передан в обработчик события 'warning' без изменений (а необязательные аргументы type, code и ctor будут проигнорированы):

import { emitWarning } from 'node:process';

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

const { emitWarning } = require('node:process');

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

Исключение TypeError возникает, если warning не является строкой или объектом Error.

Хотя предупреждения процесса используют объекты Error, механизм предупреждений процесса не заменяет стандартные механизмы обработки ошибок.

Если свойство type предупреждения равно 'DeprecationWarning', реализуется следующая дополнительная обработка:

• Если используется флаг командной строки --throw-deprecation, предупреждение об устаревании генерируется как исключение, а не как событие.
• Если используется флаг командной строки --no-deprecation, предупреждение об устаревании подавляется.
• Если используется флаг командной строки --trace-deprecation, предупреждение об устаревании выводится в stderr вместе с полным стеком вызовов.

Предотвращение дублирования предупреждений

Рекомендуется вызывать предупреждения только один раз за процесс. Для этого поместите вызов emitWarning() под условие с логической переменной.

import { emitWarning } from 'node:process';

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothing

const { emitWarning } = require('node:process');

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothing

process.env

• Тип: <Object>

Свойство process.env возвращает объект, содержащий переменные окружения пользователя. См. environ(7).

Пример такого объекта выглядит следующим образом:

{
  "TERM": "xterm-256color",
  "SHELL": "/usr/local/bin/bash",
  "USER": "maciej",
  "PATH": "~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin",
  "PWD": "/Users/maciej",
  "EDITOR": "vim",
  "SHLVL": "1",
  "HOME": "/Users/maciej",
  "LOGNAME": "maciej",
  "_": "/usr/local/bin/node"
}
jsoncopy

Этот объект можно изменять, но такие изменения не будут отражаться за пределами процесса Node.js или (если это не запрошено явно) в других потоках Worker. Другими словами, следующий пример работать не будет:

node -e 'process.env.foo = "bar"' && echo $foo
bashcopy

В то время как следующий будет работать:

import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);

const { env } = require('node:process');

env.foo = 'bar';
console.log(env.foo);

Присваивание свойства в process.env неявно преобразует значение в строку. Такое поведение признано устаревшим. Будущие версии Node.js могут выдавать ошибку, если значение не является строкой, числом или логическим значением.

import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'

const { env } = require('node:process');

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'

Используйте delete для удаления свойства из process.env.

import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined

const { env } = require('node:process');

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined

В операционных системах Windows переменные окружения нечувствительны к регистру.

import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1

const { env } = require('node:process');

env.TEST = 1;
console.log(env.test);
// => 1

Если иное не указано явно при создании экземпляра Worker, каждый поток Worker имеет собственную копию process.env, основанную на process.env родительского потока или на том, что было передано в качестве параметра env в конструктор Worker. Изменения в process.env не будут видны в других потоках Worker, и только главный поток может вносить изменения, которые видны операционной системе или нативным аддонам. В Windows копия process.env в экземпляре Worker работает с учётом регистра, в отличие от главного потока.

process.execArgv

• Тип: <string[]>

Свойство process.execArgv возвращает набор параметров командной строки, специфичных для Node.js, переданных при запуске процесса Node.js. Эти параметры не присутствуют в массиве, возвращаемом свойством process.argv, и не включают сам исполняемый файл Node.js, имя скрипта или любые параметры, следующие за именем скрипта. Эти параметры полезны для создания дочерних процессов с той же средой выполнения, что и родительский.

node --icu-data-dir=./foo --require ./bar.js script.js --version
bashcopy

Приведёт к следующему process.execArgv:

["--icu-data-dir=./foo", "--require", "./bar.js"]
jsoncopy

И к следующему process.argv:

["/usr/local/bin/node", "script.js", "--version"]
jsoncopy

Подробное описание поведения рабочих потоков с этим свойством см. в разделе конструктор Worker.

process.execPath

• Тип: <string>

Свойство process.execPath возвращает абсолютный путь к исполняемому файлу, запустившему процесс Node.js. Символические ссылки, если таковые имеются, разрешаются.

"/usr/local/bin/node"
jsoncopy

process.execve(file[, args[, env]])

• file <string> Имя или путь к исполняемому файлу для запуска.
• args <string[]> Список строковых аргументов. Ни один аргумент не может содержать нулевой байт (\u0000).
• env <Object> Пары «ключ-значение» переменных окружения. Ни один ключ или значение не могут содержать нулевой байт (\u0000). По умолчанию: process.env.

Заменяет текущий процесс новым процессом.

Это достигается с помощью POSIX-функции execve, поэтому память или другие ресурсы текущего процесса не сохраняются, за исключением файловых дескрипторов стандартного ввода, стандартного вывода и стандартной ошибки.

В случае успеха при подмене процессов все остальные ресурсы сбрасываются системой без вызова событий выхода (exit) или закрытия (close), без выполнения каких-либо обработчиков очистки JavaScript (например, process.on('exit')) и без вызова нативных колбэков AtExit, зарегистрированных через API встраивания. Если вызывающей стороне необходимо выполнить логику очистки, это следует сделать до вызова process.execve().

Эта функция не возвращает управление при успешном выполнении. В случае сбоя базового системного вызова execve(2) выбрасывается исключение Error, свойство code которого устанавливается в соответствующую строку errno (например, 'ENOENT', если file не существует), при этом свойство syscall устанавливается в 'execve', а path — в file. При сбое execve(2) текущий процесс продолжает выполняться с неизменным состоянием, что позволяет вызывающей стороне обработать ошибку и выполнить другое действие.

Эта функция недоступна в Windows или IBM i.

process.exit([code])

• code <integer> | <string> | <null> | <undefined> Код завершения. Для типа string допускаются только строки, представляющие целые числа (например, '1'). По умолчанию: 0.

Метод process.exit() предписывает Node.js синхронно завершить процесс со статусом завершения code. Если code опущен, выход использует либо код «успешно» 0, либо значение process.exitCode, если оно было установлено. Node.js не завершит работу до тех пор, пока не будут вызваны все слушатели события 'exit'.

Чтобы завершить работу с кодом «ошибка»:

import { exit } from 'node:process';

exit(1);

const { exit } = require('node:process');

exit(1);

Командная оболочка, выполнившая Node.js, должна увидеть код завершения 1.

Вызов process.exit() принудительно завершит процесс как можно быстрее, даже если все еще есть ожидающие асинхронные операции, которые еще не завершились полностью, включая операции ввода-вывода в process.stdout и process.stderr.

В большинстве ситуаций вызывать process.exit() явно нет необходимости. Процесс Node.js завершится самостоятельно, если в цикле событий нет незавершенной работы. Свойство process.exitCode можно установить, чтобы указать процессу, какой код завершения использовать при штатном завершении работы.

Например, следующий код иллюстрирует неправильное использование метода process.exit(), которое может привести к тому, что выведенные в stdout данные будут обрезаны и потеряны:

import { exit } from 'node:process';

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}

const { exit } = require('node:process');

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}

Причина возникновения этой проблемы заключается в том, что запись в process.stdout в Node.js иногда является асинхронной и может происходить в течение нескольких тиков цикла событий Node.js. Однако вызов process.exit() принудительно завершает процесс до того, как эти дополнительные операции записи в stdout будут выполнены.

Вместо прямого вызова process.exit() код должен установить process.exitCode и позволить процессу завершиться естественным путем, избегая планирования какой-либо дополнительной работы для цикла событий:

import process from 'node:process';

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

Если необходимо завершить процесс Node.js из-за ошибки, выброс неперехваченной ошибки и предоставление процессу возможности завершиться соответствующим образом безопаснее, чем вызов process.exit().

В потоках Worker эта функция останавливает текущий поток, а не текущий процесс.

process.exitCode

• Тип: <integer> | <string> | <null> | <undefined> Код завершения. Для типа string допускаются только строки, представляющие целые числа (например, '1'). По умолчанию: undefined.

Число, которое будет кодом завершения процесса при его штатном завершении либо при выходе через process.exit() без указания кода.

Значение process.exitCode может быть обновлено либо путем присваивания значения process.exitCode, либо путем передачи аргумента в process.exit():

$ node -e 'process.exitCode = 9'; echo $?
9
$ node -e 'process.exit(42)'; echo $?
42
$ node -e 'process.exitCode = 9; process.exit(42)'; echo $?
42
consolecopy

Значение также может быть установлено неявно средой Node.js при возникновении неустранимых ошибок (например, при обнаружении незавершенного top-level await). Однако явные манипуляции с кодом завершения всегда имеют приоритет над неявными:

$ node --input-type=module -e 'await new Promise(() => {})'; echo $?
13
$ node --input-type=module -e 'process.exitCode = 9; await new Promise(() => {})'; echo $?
9
consolecopy

process.features.cached_builtins

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js кэширует встроенные модули.

process.features.debug

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js является отладочной (debug build).

process.features.inspector

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает инспектор.

process.features.ipv6

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку IPv6.

Поскольку все сборки Node.js поддерживают IPv6, это значение всегда равно true.

process.features.require_module

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js поддерживает загрузку модулей ECMAScript с помощью require().

process.features.tls

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку TLS.

process.features.tls_alpn

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку ALPN в TLS.

В Node.js 11.0.0 и более поздних версиях зависимости OpenSSL имеют безусловную поддержку ALPN. Следовательно, это значение идентично значению process.features.tls.

process.features.tls_ocsp

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку OCSP в TLS.

В Node.js 11.0.0 и более поздних версиях зависимости OpenSSL имеют безусловную поддержку OCSP. Следовательно, это значение идентично значению process.features.tls.

process.features.tls_sni

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку SNI в TLS.

В Node.js 11.0.0 и более поздних версиях зависимости OpenSSL имеют безусловную поддержку SNI. Следовательно, это значение идентично значению process.features.tls.

process.features.typescript

• Тип: <boolean> | <string>

Значение, которое по умолчанию равно "strip", и равно false, если Node.js запущен с параметром --no-strip-types.

process.features.uv

• Тип: <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку libuv.

Поскольку собрать Node.js без libuv невозможно, это значение всегда равно true.

process.finalization.register(ref, callback)

• ref <Object> | <Function> Ссылка на отслеживаемый ресурс.
• callback <Function> Функция обратного вызова, вызываемая при финализации ресурса.
  • ref <Object> | <Function> Ссылка на отслеживаемый ресурс.
  • event <string> Событие, вызвавшее финализацию. По умолчанию 'exit'.

Эта функция регистрирует функцию обратного вызова, которая будет вызвана при генерации процессом события exit, если объект ref не был собран сборщиком мусора. Если объект ref был собран сборщиком мусора до того, как было сгенерировано событие exit, функция обратного вызова будет удалена из реестра финализации и не будет вызвана при завершении процесса.

Внутри функции обратного вызова можно освободить ресурсы, выделенные объектом ref. Имейте в виду, что все ограничения, применяемые к событию beforeExit, также применяются к функции callback; это означает, что существует вероятность того, что функция обратного вызова не будет вызвана при определенных обстоятельствах.

Идея этой функции заключается в том, чтобы помочь освободить ресурсы в момент, когда процесс начинает завершаться, но в то же время позволить сборщику мусора удалить объект, если он больше не используется.

Например: вы можете зарегистрировать объект, содержащий буфер; вы хотите быть уверены, что этот буфер будет освобожден при завершении процесса, но если объект собирается сборщиком мусора до завершения процесса, освобождать буфер больше не нужно, поэтому в этом случае функция обратного вызова просто удаляется из реестра финализации.

const { finalization } = require('node:process');

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  finalization.register(myDisposableObject, onFinalize);
}

setup();

import { finalization } from 'node:process';

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  finalization.register(myDisposableObject, onFinalize);
}

setup();

Приведенный выше код основан на следующих предположениях:

• стрелочные функции не используются
• обычные функции рекомендуется объявлять в глобальном контексте (root)

Обычные функции могут ссылаться на контекст, в котором существует obj, что делает obj недоступным для сборщика мусора.

Стрелочные функции будут сохранять предыдущий контекст. Рассмотрим, например:

class Test {
  constructor() {
    finalization.register(this, (ref) => ref.dispose());

    // Even something like this is highly discouraged
    // finalization.register(this, () => this.dispose());
  }
  dispose() {}
}
jscopy

Маловероятно (хотя и не исключено), что этот объект будет собран сборщиком мусора, но если этого не произойдет, dispose будет вызван при вызове process.exit.

Будьте осторожны и не полагайтесь на эту функцию для освобождения критически важных ресурсов, так как не гарантируется, что функция обратного вызова будет вызвана при любых обстоятельствах.

process.finalization.registerBeforeExit(ref, callback)

• ref <Object> | <Function> Ссылка на отслеживаемый ресурс.
• callback <Function> Функция обратного вызова, вызываемая при финализации ресурса.
  • ref <Object> | <Function> Ссылка на отслеживаемый ресурс.
  • event <string> Событие, вызвавшее финализацию. По умолчанию 'beforeExit'.

Эта функция работает точно так же, как register, за исключением того, что функция обратного вызова будет вызвана при генерации процессом события beforeExit, если объект ref не был собран сборщиком мусора.

Имейте в виду, что все ограничения, применяемые к событию beforeExit, также применяются к функции callback; это означает, что существует вероятность того, что функция обратного вызова не будет вызвана при определенных обстоятельствах.

process.finalization.unregister(ref)

• ref <Object> | <Function> Ссылка на ранее зарегистрированный ресурс.

Эта функция удаляет регистрацию объекта из реестра финализации, поэтому функция обратного вызова больше вызываться не будет.

const { finalization } = require('node:process');

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  finalization.register(myDisposableObject, onFinalize);

  // Do something

  myDisposableObject.dispose();
  finalization.unregister(myDisposableObject);
}

setup();

import { finalization } from 'node:process';

// Please make sure that the function passed to finalization.register()
// does not create a closure around unnecessary objects.
function onFinalize(obj, event) {
  // You can do whatever you want with the object
  obj.dispose();
}

function setup() {
  // This object can be safely garbage collected,
  // and the resulting shutdown function will not be called.
  // There are no leaks.
  const myDisposableObject = {
    dispose() {
      // Free your resources synchronously
    },
  };

  // Please make sure that the function passed to finalization.register()
  // does not create a closure around unnecessary objects.
  function onFinalize(obj, event) {
    // You can do whatever you want with the object
    obj.dispose();
  }

  finalization.register(myDisposableObject, onFinalize);

  // Do something

  myDisposableObject.dispose();
  finalization.unregister(myDisposableObject);
}

setup();

process.getActiveResourcesInfo()

• Возвращает: <string[]>

Метод process.getActiveResourcesInfo() возвращает массив строк, содержащий типы активных ресурсов, которые в данный момент поддерживают работу цикла событий.

import { getActiveResourcesInfo } from 'node:process';
import { setTimeout } from 'node:timers';

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

const { getActiveResourcesInfo } = require('node:process');
const { setTimeout } = require('node:timers');

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

process.getBuiltinModule(id)

• id <string> Идентификатор запрашиваемого встроенного модуля.
• Возвращает: <Object> | <undefined>

process.getBuiltinModule(id) предоставляет способ загрузки встроенных модулей с помощью глобально доступной функции. Модули ES, которым необходимо поддерживать другие среды, могут использовать его для условной загрузки встроенного модуля Node.js при выполнении в Node.js без необходимости обрабатывать ошибку разрешения модулей, которая может быть выброшена import в отличной от Node.js среде, или без использования динамического import(), который либо превращает модуль в асинхронный, либо делает синхронный API асинхронным.

if (globalThis.process?.getBuiltinModule) {
  // Run in Node.js, use the Node.js fs module.
  const fs = globalThis.process.getBuiltinModule('fs');
  // If `require()` is needed to load user-modules, use createRequire()
  const module = globalThis.process.getBuiltinModule('module');
  const require = module.createRequire(import.meta.url);
  const foo = require('foo');
}
mjscopy

Если id указывает на встроенный модуль, доступный в текущем процессе Node.js, метод process.getBuiltinModule(id) возвращает соответствующий встроенный модуль. Если id не соответствует ни одному встроенному модулю, возвращается undefined.

process.getBuiltinModule(id) принимает идентификаторы встроенных модулей, распознаваемые функцией module.isBuiltin(id). Некоторые встроенные модули должны загружаться с префиксом node:, см. встроенные модули с обязательным префиксом node:. Ссылки, возвращаемые process.getBuiltinModule(id), всегда указывают на встроенный модуль, соответствующий id, даже если пользователи модифицируют require.cache так, что require(id) возвращает что-то другое.

process.getegid()

Метод process.getegid() возвращает числовой эффективный идентификатор группы процесса Node.js. (См. getegid(2).)

import process from 'node:process';

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.geteuid()

• Возвращает: <Object>

Метод process.geteuid() возвращает числовой эффективный идентификатор пользователя процесса. (См. geteuid(2).)

import process from 'node:process';

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.getgid()

• Возвращает: <Object>

Метод process.getgid() возвращает числовой идентификатор группы процесса. (См. getgid(2).)

import process from 'node:process';

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.getgroups()

• Возвращает: <integer[]>

Метод process.getgroups() возвращает массив с дополнительными идентификаторами групп (supplementary group IDs). POSIX оставляет неопределенным, включается ли эффективный идентификатор группы, но Node.js гарантирует, что он всегда включен.

import process from 'node:process';

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.getuid()

• Возвращает: <integer>

Метод process.getuid() возвращает числовой идентификатор пользователя процесса. (См. getuid(2).)

import process from 'node:process';

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}

Эта функция недоступна в Windows.

process.hasUncaughtExceptionCaptureCallback()

• Возвращает: <boolean>

Указывает, была ли установлена функция обратного вызова с использованием process.setUncaughtExceptionCaptureCallback().

process.hrtime([time])

• time <integer[]> Результат предыдущего вызова process.hrtime()
• Возвращает: <integer[]>

Это устаревшая версия метода process.hrtime.bigint() до того, как в JavaScript был представлен bigint.

Метод process.hrtime() возвращает текущее реальное время высокого разрешения в виде кортежа [seconds, nanoseconds] Array, где nanoseconds — оставшаяся часть реального времени, которая не может быть представлена с точностью до секунд.

time — необязательный параметр, который должен быть результатом предыдущего вызова process.hrtime() для вычисления разницы с текущим временем. Если переданный параметр не является кортежем Array, будет выброшена ошибка TypeError. Передача пользовательского массива вместо результата предыдущего вызова process.hrtime() приведет к неопределенному поведению.

Эти значения времени относительны к произвольному моменту времени в прошлом, не связаны со временем суток и, следовательно, не подвержены смещению часов. Основное применение — измерение производительности между интервалами:

import { hrtime } from 'node:process';

const NS_PER_SEC = 1e9;
const time = hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);

const { hrtime } = require('node:process');

const NS_PER_SEC = 1e9;
const time = hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);

process.hrtime.bigint()

• Возвращает: <bigint>

Версия метода process.hrtime(), возвращающая bigint текущего реального времени высокого разрешения в наносекундах в виде bigint.

В отличие от process.hrtime(), она не поддерживает дополнительный аргумент time, поскольку разницу можно вычислить напрямую простым вычитанием двух значений bigint.

import { hrtime } from 'node:process';

const start = hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);

const { hrtime } = require('node:process');

const start = hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);

process.initgroups(user, extraGroup)

• user <string> | <number> Имя пользователя или числовой идентификатор.
• extraGroup <string> | <number> Имя группы или числовой идентификатор.

Метод process.initgroups() считывает файл /etc/group и инициализирует список доступа к группам, используя все группы, членом которых является пользователь. Это привилегированная операция, которая требует, чтобы процесс Node.js имел либо права доступа root, либо привилегию CAP_SETGID.

Будьте осторожны при сбросе привилегий:

import { getgroups, initgroups, setgid } from 'node:process';

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(getgroups());         // [ 27, 30, 46, 1000 ]

const { getgroups, initgroups, setgid } = require('node:process');

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(getgroups());         // [ 27, 30, 46, 1000 ]

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android). Эта возможность недоступна в потоках Worker.

process.kill(pid[, signal])

• pid <number> Идентификатор процесса
• signal <string> | <number> Сигнал для отправки в виде строки или числа. По умолчанию: 'SIGTERM'.

Метод process.kill() отправляет signal процессу, идентифицируемому pid.

Имена сигналов представляют собой строки, такие как 'SIGINT' или 'SIGHUP'. Дополнительные сведения см. в разделе События сигналов и на странице kill(2).

Этот метод выдаст ошибку, если целевой pid не существует. В качестве особого случая сигнал 0 может использоваться для проверки существования процесса. Платформы Windows выдадут ошибку, если pid используется для завершения группы процессов.

Несмотря на то, что эта функция называется process.kill(), она на самом деле лишь отправляет сигнал, подобно системному вызову kill. Отправленный сигнал может выполнять действие, отличное от завершения целевого процесса.

import process, { kill } from 'node:process';

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

kill(process.pid, 'SIGHUP');

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

process.kill(process.pid, 'SIGHUP');

Когда процесс Node.js получает SIGUSR1, Node.js запускает отладчик. См. События сигналов.

process.loadEnvFile(path)

• path <string> | <URL> | <Buffer> | <undefined>. По умолчанию: './.env'

Загружает файл .env в process.env. Использование NODE_OPTIONS в файле .env не окажет никакого влияния на Node.js.

const { loadEnvFile } = require('node:process');
loadEnvFile();

import { loadEnvFile } from 'node:process';
loadEnvFile();

process.mainModule

• Тип: <Object>

Свойство process.mainModule предоставляет альтернативный способ получения require.main. Разница заключается в том, что если главный модуль изменяется во время выполнения, require.main все еще может ссылаться на исходный главный модуль в модулях, которые были подключены до того, как произошло изменение. Как правило, можно считать, что они оба ссылаются на один и тот же модуль.

Как и в случае с require.main, process.mainModule будет иметь значение undefined, если входной скрипт отсутствует.

process.memoryUsage()

• Возвращает: <Object>
  • rss <integer>
  • heapTotal <integer>
  • heapUsed <integer>
  • external <integer>
  • arrayBuffers <integer>

Возвращает объект, описывающий использование памяти процессом Node.js, измеренное в байтах.

import { memoryUsage } from 'node:process';

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }

const { memoryUsage } = require('node:process');

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }

• heapTotal и heapUsed относятся к использованию памяти V8.
• external относится к использованию памяти C++ объектов, привязанных к объектам JavaScript под управлением V8.
• rss (Resident Set Size) — это объем пространства, занимаемый процессом в основном устройстве памяти (являющийся подмножеством общей выделенной памяти), включая все объекты C++ и JavaScript, а также код.
• arrayBuffers относится к памяти, выделенной для ArrayBuffer и SharedArrayBuffer, включая все Node.js Buffer. Это также включено в значение external. Если Node.js используется в качестве встраиваемой библиотеки, это значение может быть равным 0, поскольку выделение памяти для ArrayBuffer в этом случае может не отслеживаться.

При использовании потоков Worker значение rss будет актуально для всего процесса, тогда как остальные поля будут относиться только к текущему потоку.

Метод process.memoryUsage() выполняет итерацию по каждой странице для сбора информации об использовании памяти, что может происходить медленно в зависимости от распределения памяти в программе.

Примечание о process memoryUsage

В Linux или других системах, где обычно используется glibc, приложение может демонстрировать устойчивый рост rss несмотря на стабильный heapTotal из-за фрагментации, вызванной реализацией malloc в glibc. См. nodejs/node#21973 о том, как переключиться на альтернативную реализацию malloc для решения этой проблемы с производительностью.

process.memoryUsage.rss()

• Возвращает: <integer>

Метод process.memoryUsage.rss() возвращает целое число, представляющее размер резидентного набора (RSS) в байтах.

Размер резидентного набора (Resident Set Size) — это объем пространства, занимаемый процессом в основном устройстве памяти (являющийся подмножеством общей выделенной памяти), включая все объекты C++ и JavaScript, а также код.

Это то же значение, что и свойство rss, возвращаемое process.memoryUsage(), но process.memoryUsage.rss() работает быстрее.

import { memoryUsage } from 'node:process';

console.log(memoryUsage.rss());
// 35655680

const { memoryUsage } = require('node:process');

console.log(memoryUsage.rss());
// 35655680

process.nextTick(callback[, ...args])

• callback <Function>
• ...args <any> Дополнительные аргументы, передаваемые при вызове callback

process.nextTick() добавляет callback в "очередь next tick". Эта очередь полностью опустошается после завершения текущей операции в стеке JavaScript и до того, как циклу событий будет позволено продолжить работу. Можно создать бесконечный цикл, если рекурсивно вызывать process.nextTick(). Дополнительные сведения см. в руководстве по циклу событий.

import { nextTick } from 'node:process';

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callback

const { nextTick } = require('node:process');

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callback

Это важно при разработке API, чтобы дать пользователям возможность назначать обработчики событий после создания объекта, но до выполнения какого-либо ввода-вывода:

import { nextTick } from 'node:process';

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.

const { nextTick } = require('node:process');

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.

Очень важно, чтобы API были либо на 100% синхронными, либо на 100% асинхронными. Рассмотрим этот пример:

// WARNING!  DO NOT USE!  BAD UNSAFE HAZARD!
function maybeSync(arg, cb) {
  if (arg) {
    cb();
    return;
  }

  fs.stat('file', cb);
}
jscopy

Такой API опасен, так как в следующем случае:

const maybeTrue = Math.random() > 0.5;

maybeSync(maybeTrue, () => {
  foo();
});

bar();
jscopy

Неясно, что будет вызвано раньше: foo() или bar().

Следующий подход значительно лучше:

import { nextTick } from 'node:process';

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}

const { nextTick } = require('node:process');

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}

Когда использовать queueMicrotask() вместо process.nextTick()

API queueMicrotask() является альтернативой process.nextTick(), которая вместо "очереди next tick" откладывает выполнение функции с использованием той же очереди микрозадач, которая применяется для выполнения обработчиков then, catch и finally разрешенных промисов.

В Node.js каждый раз при опустошении "очереди next tick" сразу после нее опустошается очередь микрозадач.

Поэтому в модулях CJS функции обратного вызова process.nextTick() всегда запускаются перед вызовами queueMicrotask(). Однако, поскольку модули ESM уже обрабатываются как часть очереди микрозадач, там функции обратного вызова queueMicrotask() всегда выполняются перед вызовами process.nextTick(), так как Node.js уже находится в процессе опустошения очереди микрозадач.

import { nextTick } from 'node:process';

Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// resolve
// microtask
// nextTick

const { nextTick } = require('node:process');

Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// nextTick
// resolve
// microtask

Для большинства пользовательских сценариев использования API queueMicrotask() предоставляет переносимый и надежный механизм отложенного выполнения, работающий в различных средах платформ JavaScript, и ему следует отдавать предпочтение перед process.nextTick(). В простых сценариях queueMicrotask() может служить прямой заменой для process.nextTick().

console.log('start');
queueMicrotask(() => {
  console.log('microtask callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// microtask callback
jscopy

Одно примечательное различие между этими двумя API заключается в том, что process.nextTick() позволяет указывать дополнительные значения, которые будут переданы в качестве аргументов в отложенную функцию при ее вызове. Достижение того же результата с помощью queueMicrotask() требует использования замыкания либо привязанной функции:

function deferred(a, b) {
  console.log('microtask', a + b);
}

console.log('start');
queueMicrotask(deferred.bind(undefined, 1, 2));
console.log('scheduled');
// Output:
// start
// scheduled
// microtask 3
jscopy

Существуют незначительные различия в обработке ошибок, возникающих внутри очереди next tick и очереди микрозадач. Ошибки, выброшенные внутри обратного вызова в очереди микрозадач, по возможности должны обрабатываться внутри самого обратного вызова. Если они не обработаны, можно использовать обработчик события process.on('uncaughtException') для перехвата и обработки ошибок.

В случае сомнений, если не требуются специфические возможности process.nextTick(), используйте queueMicrotask().

process.noDeprecation

• Тип: <boolean>

Свойство process.noDeprecation указывает, установлен ли флаг --no-deprecation для текущего процесса Node.js. Дополнительные сведения о поведении этого флага см. в документации по событию 'warning' и методу emitWarning().

process.permission

• Тип: <Object>

Этот API доступен через флаг --permission.

process.permission — это объект, методы которого используются для управления разрешениями текущего процесса. Дополнительная документация доступна в разделе Модель разрешений.

process.permission.has(scope[, reference])

• scope <string>
• reference <string>
• Возвращает: <boolean>

Проверяет, имеет ли процесс доступ к заданной области (scope) и ссылке (reference). Если ссылка не указана, предполагается глобальная область, например, process.permission.has('fs.read') проверит, имеет ли процесс ВСЕ разрешения на чтение файловой системы.

Значение ссылки зависит от указанной области видимости. Например, когда областью является файловая система, ссылка означает файлы и папки.

Доступные области:

• fs — вся файловая система
• fs.read — операции чтения файловой системы
• fs.write — операции записи файловой системы
• child — операции порождения дочерних процессов
• worker — операции создания рабочих потоков (worker threads)
• ffi — операции интерфейса внешних функций (FFI)

// Check if the process has permission to read the README file
process.permission.has('fs.read', './README.md');
// Check if the process has read permission operations
process.permission.has('fs.read');
jscopy

process.permission.drop(scope[, reference])

• scope <string>
• reference <string>

Сбрасывает указанное разрешение для текущего процесса. Эта операция необратима: после отзыва разрешения его невозможно восстановить ни через какой API Node.js.

Если ссылка не указана, сбрасывается вся область. Например, process.permission.drop('fs.read') отзовет ВСЕ разрешения на чтение файловой системы.

Если ссылка указана, сбрасывается только разрешение для этого конкретного ресурса. Например, process.permission.drop('fs.read', '/etc/myapp') отзовет доступ на чтение к этому каталогу, сохраняя остальные разрешения на чтение нетронутыми.

Важно: вы можете сбросить только тот ресурс, который был явно предоставлен. Ссылка, переданная в drop(), должна соответствовать исходному разрешению:

• Если разрешение было предоставлено с использованием подстановочного знака (*), например --allow-fs-read=*, отдельные пути не могут быть сброшены — может быть сброшена только вся область целиком (путем вызова drop() без ссылки).
• Если был предоставлен каталог (например, --allow-fs-read=/my/folder), вы не можете отозвать доступ к отдельным файлам внутри него. Необходимо сбросить тот же каталог, который был предоставлен. Любые оставшиеся разрешения продолжают действовать.

Доступные области совпадают с process.permission.has():

• fs — вся файловая система (сбрасывает как чтение, так и запись)
• fs.read — операции чтения файловой системы
• fs.write — операции записи файловой системы
• child — операции порождения дочерних процессов
• worker — операции создания рабочих потоков
• net — сетевые операции
• inspector — операции инспектора
• wasi — операции WASI
• addon — операции нативных аддонов

const fs = require('node:fs');

// Read configuration during startup
const config = fs.readFileSync('/etc/myapp/config.json', 'utf8');

// Drop read access to the config directory after initialization
process.permission.drop('fs.read', '/etc/myapp');

// This will now throw ERR_ACCESS_DENIED
fs.readFileSync('/etc/myapp/config.json');
jscopy

process.pid

• Тип: <integer>

Свойство process.pid возвращает PID процесса.

import { pid } from 'node:process';

console.log(`This process is pid ${pid}`);

const { pid } = require('node:process');

console.log(`This process is pid ${pid}`);

process.platform

• Тип: <string>

Свойство process.platform возвращает строку, идентифицирующую платформу операционной системы, для которой был скомпилирован исполняемый файл Node.js.

В настоящее время возможные значения:

• 'aix'
• 'darwin'
• 'freebsd'
• 'linux'
• 'openbsd'
• 'sunos'
• 'win32'

import { platform } from 'node:process';

console.log(`This platform is ${platform}`);

const { platform } = require('node:process');

console.log(`This platform is ${platform}`);

Значение 'android' также может возвращаться, если Node.js собран в операционной системе Android. Однако поддержка Android в Node.js является экспериментальной.

process.ppid

• Тип: <integer>

Свойство process.ppid возвращает PID родительского процесса текущего процесса.

import { ppid } from 'node:process';

console.log(`The parent process is pid ${ppid}`);

const { ppid } = require('node:process');

console.log(`The parent process is pid ${ppid}`);

process.ref(maybeRefable)

• maybeRefable <any> Объект, который может быть "refable".

Объект является "refable", если он реализует "Refable protocol" в Node.js. В частности, это означает, что объект реализует методы Symbol.for('nodejs.ref') и Symbol.for('nodejs.unref'). Объекты с активной ссылкой ("Ref'd") сохраняют цикл событий Node.js активным, тогда как объекты со снятой ссылкой ("unref'd") — нет. Исторически это реализовывалось с помощью вызова методов ref() и unref() непосредственно у объектов. Однако этот паттерн объявляется устаревшим в пользу "протокола Refable", чтобы лучше поддерживать типы Web Platform API, API которых нельзя модифицировать для добавления методов ref() и unref(), но которым по-прежнему необходимо поддерживать такое поведение.

process.release

• Тип: <Object>

Свойство process.release возвращает Object, содержащий метаданные, относящиеся к текущему релизу, включая URL-адреса исходного архива tarball и архива tarball, содержащего только заголовки.

process.release содержит следующие свойства:

• name <string> Значение, которое всегда будет равно 'node'.
• sourceUrl <string> абсолютный URL-адрес, указывающий на файл .tar.gz, содержащий исходный код текущего релиза.
• headersUrl<string> абсолютный URL-адрес, указывающий на файл .tar.gz, содержащий только файлы заголовков исходного кода для текущего релиза. Этот файл значительно меньше полного файла исходного кода и может использоваться для компиляции нативных аддонов Node.js.
• libUrl <string> | <undefined> абсолютный URL-адрес, указывающий на файл node.lib, соответствующий архитектуре и версии текущего релиза. Этот файл используется для компиляции нативных аддонов Node.js. Это свойство присутствует только в сборках Node.js для Windows и отсутствует на всех остальных платформах.
• lts <string> | <undefined> строковая метка, идентифицирующая метку LTS для этого релиза. Это свойство существует только для релизов LTS и имеет значение undefined для всех остальных типов релизов, включая релизы Current. Допустимые значения включают кодовые имена релизов LTS (включая те, которые больше не поддерживаются).
  • 'Fermium' для линейки 14.x LTS, начиная с 14.15.0.
  • 'Gallium' для линейки 16.x LTS, начиная с 16.13.0.
  • 'Hydrogen' для линейки 18.x LTS, начиная с 18.12.0. Кодовые имена других релизов LTS см. в архиве журналов изменений Node.js

{
  "name": "node",
  "lts": "Hydrogen",
  "sourceUrl": "https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz",
  "headersUrl": "https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz",
  "libUrl": "https://nodejs.org/download/release/v18.12.0/win-x64/node.lib"
}
jsoncopy

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

process.report

• Тип: <Object>

process.report — это объект, методы которого используются для создания диагностических отчетов для текущего процесса. Дополнительная документация доступна в документации по отчетам.

process.report.compact

• Тип: <boolean>

Записывать отчеты в компактном формате — однострочном JSON, который легче обрабатывается системами анализа логов, чем формат по умолчанию со множеством строк, предназначенный для чтения человеком.

import { report } from 'node:process';

console.log(`Reports are compact? ${report.compact}`);

const { report } = require('node:process');

console.log(`Reports are compact? ${report.compact}`);

process.report.directory

• Тип: <string>

Каталог, в который записывается отчет. Значением по умолчанию является пустая строка, что указывает на запись отчетов в текущий рабочий каталог процесса Node.js.

import { report } from 'node:process';

console.log(`Report directory is ${report.directory}`);

const { report } = require('node:process');

console.log(`Report directory is ${report.directory}`);

process.report.filename

• Тип: <string>

Имя файла, в который записывается отчет. Если установлено в пустую строку, имя выходного файла будет сформировано из метки времени, PID и порядкового номера. Значением по умолчанию является пустая строка.

Если значение process.report.filename установлено в 'stdout' или 'stderr', отчет записывается соответственно в stdout или stderr процесса.

import { report } from 'node:process';

console.log(`Report filename is ${report.filename}`);

const { report } = require('node:process');

console.log(`Report filename is ${report.filename}`);

process.report.getReport([err])

• err <Error> Пользовательская ошибка, используемая для предоставления стека JavaScript.
• Возвращает: <Object>

Возвращает представление диагностического отчета для работающего процесса в виде объекта JavaScript. Трассировка стека JavaScript для отчета берется из err, если он указан.

import { report } from 'node:process';
import util from 'node:util';

const data = report.getReport();
console.log(data.header.nodejsVersion);

// Similar to process.report.writeReport()
import fs from 'node:fs';
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8');

const { report } = require('node:process');
const util = require('node:util');

const data = report.getReport();
console.log(data.header.nodejsVersion);

// Similar to process.report.writeReport()
const fs = require('node:fs');
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8');

Дополнительная документация доступна в документации по отчетам.

process.report.reportOnFatalError

• Тип: <boolean>

Если true, диагностический отчет создается при фатальных ошибках, таких как нехватка памяти или сбой утверждений (assertions) C++.

import { report } from 'node:process';

console.log(`Report on fatal error: ${report.reportOnFatalError}`);

const { report } = require('node:process');

console.log(`Report on fatal error: ${report.reportOnFatalError}`);

process.report.reportOnSignal

• Тип: <boolean>

Если установлено в true, диагностический отчет создается, когда процесс получает сигнал, указанный в process.report.signal.

import { report } from 'node:process';

console.log(`Report on signal: ${report.reportOnSignal}`);

const { report } = require('node:process');

console.log(`Report on signal: ${report.reportOnSignal}`);

process.report.reportOnUncaughtException

• Тип: <boolean>

Если установлено в true, диагностический отчет создается при необработанном исключении.

import { report } from 'node:process';

console.log(`Report on exception: ${report.reportOnUncaughtException}`);

const { report } = require('node:process');

console.log(`Report on exception: ${report.reportOnUncaughtException}`);

process.report.excludeEnv

• Тип: <boolean>

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

process.report.signal

• Тип: <string>

Сигнал, используемый для запуска создания диагностического отчета. По умолчанию 'SIGUSR2'.

import { report } from 'node:process';

console.log(`Report signal: ${report.signal}`);

const { report } = require('node:process');

console.log(`Report signal: ${report.signal}`);

process.report.writeReport([filename][, err])

• filename <string> Имя файла, в который записывается отчет. Это должен быть относительный путь, который будет добавлен к каталогу, указанному в process.report.directory, или к текущему рабочему каталогу процесса Node.js, если он не указан.

• err <Error> Пользовательская ошибка, используемая для создания отчета о стеке JavaScript.

• Возвращает: <string> Возвращает имя файла сгенерированного отчета.

Записывает диагностический отчет в файл. Если параметр filename не передан, имя файла по умолчанию будет включать дату, время, PID и порядковый номер. Трассировка стека JavaScript для отчета берется из err, если параметр указан.

Если значение filename установлено в 'stdout' или 'stderr', отчет записывается соответственно в stdout или stderr процесса.

import { report } from 'node:process';

report.writeReport();

const { report } = require('node:process');

report.writeReport();

Дополнительная документация доступна в документации по отчетам.

process.resourceUsage()

• Возвращает: <Object> использование ресурсов текущим процессом. Все эти значения получены из вызова uv_getrusage, возвращающего структуру uv_rusage_t.
  • userCPUTime <integer> соответствует ru_utime, вычисленному в микросекундах. Это то же значение, что и у process.cpuUsage().user.
  • systemCPUTime <integer> соответствует ru_stime, вычисленному в микросекундах. Это то же значение, что и у process.cpuUsage().system.
  • maxRSS <integer> соответствует ru_maxrss, представляющему собой максимальный размер резидентного набора (RSS), использованный процессом, в кибибайтах (1024 байта).
  • sharedMemorySize <integer> соответствует ru_ixrss, но не поддерживается ни на одной платформе.
  • unsharedDataSize <integer> соответствует ru_idrss, но не поддерживается ни на одной платформе.
  • unsharedStackSize <integer> соответствует ru_isrss, но не поддерживается ни на одной платформе.
  • minorPageFault <integer> соответствует ru_minflt, то есть количеству незначительных сбоев страниц (minor page faults) процесса, подробнее см. в этой статье.
  • majorPageFault <integer> соответствует ru_majflt, то есть количеству серьезных сбоев страниц (major page faults) процесса, подробнее см. в этой статье. Это поле не поддерживается в Windows.
  • swappedOut <integer> соответствует ru_nswap, но не поддерживается ни на одной платформе.
  • fsRead <integer> соответствует ru_inblock, то есть количеству операций ввода, выполненных файловой системой.
  • fsWrite <integer> соответствует ru_oublock, то есть количеству операций вывода, выполненных файловой системой.
  • ipcSent <integer> соответствует ru_msgsnd, но не поддерживается ни на одной платформе.
  • ipcReceived <integer> соответствует ru_msgrcv, но не поддерживается ни на одной платформе.
  • signalsCount <integer> соответствует ru_nsignals, но не поддерживается ни на одной платформе.
  • voluntaryContextSwitches <integer> соответствует ru_nvcsw, то есть количеству добровольных переключений контекста процессора из-за того, что процесс уступил процессор до окончания своего кванта времени (обычно в ожидании доступности ресурса). Это поле не поддерживается в Windows.
  • involuntaryContextSwitches <integer> соответствует ru_nivcsw, то есть количеству принудительных переключений контекста процессора из-за того, что процесс с более высоким приоритетом стал готовым к выполнению, или из-за исчерпания процессом своего кванта времени. Это поле не поддерживается в Windows.

import { resourceUsage } from 'node:process';

console.log(resourceUsage());
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/

const { resourceUsage } = require('node:process');

console.log(resourceUsage());
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/

process.send(message[, sendHandle[, options]][, callback])

• message <Object>
• sendHandle <net.Server> | <net.Socket>
• options <Object> используется для параметризации отправки дескрипторов определенных типов. options поддерживает следующие свойства:
  • keepOpen <boolean> Значение, которое можно использовать при передаче экземпляров net.Socket. Если равно true, сокет остается открытым в процессе-отправителе. По умолчанию: false.
• callback <Function>
• Возвращает: <boolean>

Если Node.js запущен с IPC-каналом, метод process.send() можно использовать для отправки сообщений родительскому процессу. Сообщения будут получены как событие 'message' на родительском объекте ChildProcess.

Если Node.js был запущен без IPC-канала, process.send будет равен undefined.

Сообщение проходит через сериализацию и парсинг. Итоговое сообщение может отличаться от первоначально отправленного.

process.setegid(id)

• id <string> | <number> Имя или идентификатор (ID) группы

Метод process.setegid() устанавливает эффективный идентификатор группы процесса. (См. setegid(2).) Аргумент id может быть передан как числовой ID или строка с именем группы. Если указано имя группы, этот метод блокирует выполнение на время разрешения соответствующего числового ID.

import process from 'node:process';

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`);
  try {
    process.setegid(501);
    console.log(`New gid: ${process.getegid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`);
  try {
    process.setegid(501);
    console.log(`New gid: ${process.getegid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}

Эта функция доступна только на платформах POSIX (то есть не на Windows или Android). Эта возможность недоступна в потоках Worker.

process.seteuid(id)

• id <string> | <number> Имя или идентификатор (ID) пользователя

Метод process.seteuid() устанавливает эффективный идентификатор пользователя процесса. (См. seteuid(2).) Аргумент id может быть передан как числовой ID или строка с именем пользователя. Если указано имя пользователя, метод блокирует выполнение на время разрешения соответствующего числового ID.

import process from 'node:process';

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
  try {
    process.seteuid(501);
    console.log(`New uid: ${process.geteuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
  try {
    process.seteuid(501);
    console.log(`New uid: ${process.geteuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}

Эта функция доступна только на платформах POSIX (то есть не на Windows или Android). Эта возможность недоступна в потоках Worker.

process.setgid(id)

• id <string> | <number> Имя или идентификатор (ID) группы

Метод process.setgid() устанавливает идентификатор группы процесса. (См. setgid(2).) Аргумент id может быть передан как числовой ID или строка с именем группы. Если указано имя группы, этот метод блокирует выполнение на время разрешения соответствующего числового ID.

import process from 'node:process';

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`);
  try {
    process.setgid(501);
    console.log(`New gid: ${process.getgid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`);
  try {
    process.setgid(501);
    console.log(`New gid: ${process.getgid()}`);
  } catch (err) {
    console.error(`Failed to set gid: ${err}`);
  }
}

Эта функция доступна только на платформах POSIX (то есть не на Windows или Android). Эта возможность недоступна в потоках Worker.

process.setgroups(groups)

• groups <integer[]>

Метод process.setgroups() устанавливает дополнительные идентификаторы групп для процесса Node.js. Это привилегированная операция, которая требует наличия у процесса Node.js прав root или привилегии (capability) CAP_SETGID.

Массив groups может содержать числовые идентификаторы групп, имена групп или то и другое.

import process from 'node:process';

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501]);
    console.log(process.getgroups()); // new groups
  } catch (err) {
    console.error(`Failed to set groups: ${err}`);
  }
}

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501]);
    console.log(process.getgroups()); // new groups
  } catch (err) {
    console.error(`Failed to set groups: ${err}`);
  }
}

Эта функция доступна только на платформах POSIX (то есть не на Windows или Android). Эта возможность недоступна в потоках Worker.

process.setuid(id)

• id <integer> | <string>

Метод process.setuid(id) устанавливает идентификатор пользователя процесса. (См. setuid(2).) Аргумент id может быть передан как числовой ID или строка с именем пользователя. Если указано имя пользователя, метод блокирует выполнение на время разрешения соответствующего числового ID.

import process from 'node:process';

if (process.getuid && process.setuid) {
  console.log(`Current uid: ${process.getuid()}`);
  try {
    process.setuid(501);
    console.log(`New uid: ${process.getuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}

if (process.getuid && process.setuid) {
  console.log(`Current uid: ${process.getuid()}`);
  try {
    process.setuid(501);
    console.log(`New uid: ${process.getuid()}`);
  } catch (err) {
    console.error(`Failed to set uid: ${err}`);
  }
}

Эта функция доступна только на платформах POSIX (то есть не на Windows или Android). Эта возможность недоступна в потоках Worker.

process.setSourceMapsEnabled(val)

• val <boolean>

Эта функция включает или отключает поддержку Source Map для трассировки стека.

Она предоставляет те же возможности, что и запуск процесса Node.js с параметрами командной строки --enable-source-maps.

Будут проанализированы и загружены только исходные карты (source maps) в файлах JavaScript, загруженных после включения поддержки карт исходного кода.

Это подразумевает вызов module.setSourceMapsSupport() с параметром { nodeModules: true, generatedCode: true }.

process.setUncaughtExceptionCaptureCallback(fn)

• fn <Function> | <null>

Функция process.setUncaughtExceptionCaptureCallback() задает функцию, которая будет вызвана при возникновении необработанного исключения и получит само значение исключения в качестве первого аргумента.

Если такая функция задана, событие 'uncaughtException' генерироваться не будет. Если флаг --abort-on-uncaught-exception был передан из командной строки или установлен через v8.setFlagsFromString(), процесс не будет аварийно завершен. Действия, настроенные на выполнение при исключениях, такие как генерация отчетов, также будут затронуты

Чтобы отменить захватывающую функцию, можно использовать process.setUncaughtExceptionCaptureCallback(null). Вызов этого метода с аргументом, отличным от null, когда уже установлена другая функция перехвата, приведет к выбросу ошибки.

Чтобы зарегистрировать несколько одновременно работающих колбэков, используйте вместо этого process.addUncaughtExceptionCaptureCallback().

process.sourceMapsEnabled

• Тип: <boolean>

Свойство process.sourceMapsEnabled возвращает, включена ли поддержка Source Map для трассировки стека.

process.stderr

• Тип: <Stream>

Свойство process.stderr возвращает поток, подключенный к stderr (fd 2). Это поток net.Socket (являющийся дуплексным потоком Duplex), если fd 2 не указывает на файл, в случае чего это поток для записи Writable.

process.stderr существенно отличается от других потоков Node.js. Дополнительные сведения см. в разделе замечание о вводе-выводе процесса.

process.stderr.fd

• Тип: <number>

Это свойство указывает на значение базового файлового дескриптора для process.stderr. Значение фиксировано и равно 2. В потоках Worker это поле отсутствует.

process.stdin

• Тип: <Stream>

Свойство process.stdin возвращает поток, подключенный к stdin (fd 0). Это поток net.Socket (являющийся дуплексным потоком Duplex), если fd 0 не указывает на файл, в случае чего это поток для чтения Readable.

Подробнее о том, как читать из stdin, см. в readable.read().

Будучи потоком Duplex, process.stdin также может использоваться в «старом» режиме, совместимом со скриптами, написанными для Node.js до версии v0.10. Дополнительные сведения см. в разделе Совместимость потоков.

В «старом» режиме потоков поток stdin по умолчанию приостановлен, поэтому для чтения из него необходимо вызвать process.stdin.resume(). Также обратите внимание, что сам вызов process.stdin.resume() переключает поток в «старый» режим.

process.stdin.fd

• Тип: <number>

Это свойство указывает на значение базового файлового дескриптора для process.stdin. Значение фиксировано и равно 0. В потоках Worker это поле отсутствует.

process.stdout

• Тип: <Stream>

Свойство process.stdout возвращает поток, подключенный к stdout (fd 1). Это поток net.Socket (являющийся дуплексным потоком Duplex), если fd 1 не указывает на файл, в случае чего это поток для записи Writable.

Например, чтобы скопировать process.stdin в process.stdout:

import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);

const { stdin, stdout } = require('node:process');

stdin.pipe(stdout);

process.stdout существенно отличается от других потоков Node.js. Дополнительные сведения см. в разделе замечание о вводе-выводе процесса.

process.stdout.fd

• Тип: <number>

Это свойство указывает на значение базового файлового дескриптора для process.stdout. Значение фиксировано и равно 1. В потоках Worker это поле отсутствует.

Замечание о вводе-выводе процесса

process.stdout и process.stderr существенно отличаются от других потоков Node.js в важных аспектах:

1. Они используются внутри console.log() и console.error() соответственно.
2. Операции записи могут быть синхронными в зависимости от того, к чему подключен поток, и от операционной системы (Windows или POSIX):
   • Файлы: синхронно в Windows и POSIX
   • TTY (терминалы): асинхронно в Windows, синхронно в POSIX
   • Каналы (pipes и сокеты): синхронно в Windows, асинхронно в POSIX

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

Синхронная запись позволяет избежать таких проблем, как неожиданное перемежение вывода, записанного с помощью console.log() или console.error(), либо его полное отсутствие, если process.exit() вызывается до завершения асинхронной записи. Дополнительные сведения см. в разделе process.exit().

Предупреждение: синхронные операции записи блокируют цикл событий (event loop) до завершения записи. В случае вывода в файл это может происходить практически мгновенно, однако при высокой нагрузке на систему, нечитаемых на принимающей стороне пайпах, либо при медленных терминалах или файловых системах цикл событий может блокироваться достаточно часто и надолго, что приводит к серьезным проблемам с производительностью. Это может быть не критично при выводе в интерактивную сессию терминала, но к этому следует относиться с особой осторожностью при промышленном логировании в выходные потоки процесса.

Чтобы проверить, подключен ли поток к контексту TTY, проверьте свойство isTTY.

Например:

$ node -p "Boolean(process.stdin.isTTY)"
true
$ echo "foo" | node -p "Boolean(process.stdin.isTTY)"
false
$ node -p "Boolean(process.stdout.isTTY)"
true
$ node -p "Boolean(process.stdout.isTTY)" | cat
false
consolecopy

Дополнительные сведения см. в документации по TTY.

process.throwDeprecation

• Тип: <boolean>

Начальное значение process.throwDeprecation указывает, установлен ли флаг --throw-deprecation для текущего процесса Node.js. process.throwDeprecation является изменяемым, поэтому приводят ли предупреждения об устаревании к ошибкам или нет, можно настроить во время выполнения. Дополнительные сведения см. в документации по событию 'warning' и методу emitWarning().

$ node --throw-deprecation -p "process.throwDeprecation"
true
$ node -p "process.throwDeprecation"
undefined
$ node
> process.emitWarning('test', 'DeprecationWarning');
undefined
> (node:26598) DeprecationWarning: test
> process.throwDeprecation = true;
true
> process.emitWarning('test', 'DeprecationWarning');
Thrown:
[DeprecationWarning: test] { name: 'DeprecationWarning' }
consolecopy

process.threadCpuUsage([previousValue])

• previousValue <Object> Предыдущее возвращаемое значение вызова process.threadCpuUsage()
• Возвращает: <Object>
  • user <integer>
  • system <integer>

Метод process.threadCpuUsage() возвращает время использования ЦП в пользовательском и системном режимах для текущего рабочего потока (worker thread) в виде объекта со свойствами user и system, значения которых выражены в микросекундах (миллионных долях секунды).

Результат предыдущего вызова process.threadCpuUsage() можно передать в функцию в качестве аргумента, чтобы получить разностные показания.

process.title

• Тип: <string>

Свойство process.title возвращает заголовок текущего процесса (т. е. возвращает текущее значение ps). Присвоение нового значения свойству process.title изменяет текущее значение ps.

При присвоении нового значения различные платформы накладывают разные ограничения на максимальную длину заголовка. Как правило, эти ограничения довольно строгие. Например, в Linux и macOS process.title ограничен размером имени бинарного файла плюс длина аргументов командной строки, поскольку установка process.title перезаписывает память процесса argv. Node.js 0.8 допускал более длинные строки заголовка процесса, также перезаписывая память environ, но это было потенциально небезопасно и приводило к путанице в некоторых (довольно редких) случаях.

Присвоение значения свойству process.title может не привести к точному отображению метки в приложениях диспетчера процессов, таких как Мониторинг системы (Activity Monitor) в macOS или Диспетчер служб в Windows.

process.traceDeprecation

• Тип: <boolean>

Свойство process.traceDeprecation указывает, установлен ли флаг --trace-deprecation для текущего процесса Node.js. Дополнительную информацию о поведении этого флага см. в документации к событию 'warning' и методу emitWarning().

process.traceProcessWarnings

• <boolean>

Свойство process.traceProcessWarnings указывает, установлен ли флаг --trace-warnings для текущего процесса Node.js. Это свойство позволяет программно управлять трассировкой предупреждений, включая или отключая трассировку стека для предупреждений во время выполнения.

// Enable trace warnings
process.traceProcessWarnings = true;

// Emit a warning with a stack trace
process.emitWarning('Warning with stack trace');

// Disable trace warnings
process.traceProcessWarnings = false;
jscopy

process.umask()

process.umask() возвращает маску создания режимов файлов (umask) процесса Node.js. Дочерние процессы наследуют маску от родительского процесса.

process.umask(mask)

• mask <string> | <integer>

process.umask(mask) устанавливает маску создания режимов файлов процесса Node.js. Дочерние процессы наследуют маску от родительского процесса. Возвращает предыдущую маску.

import { umask } from 'node:process';

const newmask = 0o022;
const oldmask = umask(newmask);
console.log(
  `Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`,
);

const { umask } = require('node:process');

const newmask = 0o022;
const oldmask = umask(newmask);
console.log(
  `Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`,
);

В потоках Worker метод process.umask(mask) выбросит исключение.

process.unref(maybeRefable)

• maybeRefable <any> Объект, для которого может быть вызван "unref".

Объект является «unrefable», если он реализует «протокол Refable» Node.js. В частности, это означает, что объект реализует методы Symbol.for('nodejs.ref') и Symbol.for('nodejs.unref'). Объекты, к которым применен «ref», поддерживают цикл событий Node.js активным, тогда как объекты с «unref» — нет. Исторически это реализовывалось с помощью методов ref() и unref() непосредственно у самих объектов. Однако этот подход объявляется устаревшим в пользу «протокола Refable» для лучшей поддержки типов Web Platform API, чьи API нельзя изменить для добавления методов ref() и unref(), но которым все равно необходимо поддерживать такое поведение.

process.uptime()

• Возвращает: <number>

Метод process.uptime() возвращает количество секунд, в течение которых работает текущий процесс Node.js.

Возвращаемое значение включает доли секунды. Используйте Math.floor() для получения целых секунд.

process.version

• Тип: <string>

Свойство process.version содержит строку версии Node.js.

import { version } from 'node:process';

console.log(`Version: ${version}`);
// Version: v14.8.0

const { version } = require('node:process');

console.log(`Version: ${version}`);
// Version: v14.8.0

Чтобы получить строку версии без префикса v, используйте process.versions.node.

process.versions

• Тип: <Object>

Свойство process.versions возвращает объект со строками версий Node.js и его зависимостей. process.versions.modules указывает текущую версию ABI, которая увеличивается при каждом изменении C++ API. Node.js откажется загружать модули, скомпилированные для другой версии ABI модуля.

import { versions } from 'node:process';

console.log(versions);

const { versions } = require('node:process');

console.log(versions);

Сгенерирует объект, аналогичный следующему:

{ node: '26.0.0-pre',
  acorn: '8.15.0',
  ada: '3.4.1',
  amaro: '1.1.5',
  ares: '1.34.6',
  brotli: '1.2.0',
  merve: '1.0.0',
  cldr: '48.0',
  icu: '78.2',
  llhttp: '9.3.0',
  modules: '144',
  napi: '10',
  nbytes: '0.1.1',
  ncrypto: '0.0.1',
  nghttp2: '1.68.0',
  nghttp3: '',
  ngtcp2: '',
  openssl: '3.5.4',
  simdjson: '4.2.4',
  simdutf: '7.3.3',
  sqlite: '3.51.2',
  tz: '2025c',
  undici: '7.18.2',
  unicode: '17.0',
  uv: '1.51.0',
  uvwasi: '0.0.23',
  v8: '14.3.127.18-node.10',
  zlib: '1.3.1-e00f703',
  zstd: '1.5.7' }
consolecopy

Коды выхода

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

• 1 Неперехваченное фатальное исключение: произошло неперехваченное исключение, которое не было обработано доменом или обработчиком события 'uncaughtException'.
• 2: не используется (зарезервировано Bash для неверного использования встроенных команд)
• 3 Внутренняя ошибка синтаксического анализа JavaScript: исходный код JavaScript, используемый внутри процесса начальной загрузки Node.js, вызвал ошибку синтаксического анализа. Это происходит крайне редко и обычно возможно только во время разработки самой платформы Node.js.
• 4 Внутренняя ошибка выполнения JavaScript: исходный код JavaScript, используемый внутри процесса начальной загрузки Node.js, не вернул значение функции при вычислении. Это происходит крайне редко и обычно возможно только во время разработки самой платформы Node.js.
• 5 Фатальная ошибка: произошла фатальная неустранимая ошибка в V8. Обычно в stderr выводится сообщение с префиксом FATAL ERROR.
• 6 Внутренний обработчик исключений не является функцией: произошло неперехваченное исключение, но внутренняя функция-обработчик фатальных исключений оказалась не функцией и не смогла быть вызвана.
• 7 Ошибка во время выполнения внутреннего обработчика исключений: произошло неперехваченное исключение, и сама внутренняя функция-обработчик фатальных исключений выбросила ошибку при попытке ее обработать. Это может произойти, например, если обработчик 'uncaughtException' или domain.on('error') выбрасывает ошибку.
• 8: не используется. В предыдущих версиях Node.js код выхода 8 иногда указывал на неперехваченное исключение.
• 9 Недопустимый аргумент: была указана неизвестная опция либо опция, требующая значения, была передана без него.
• 10 Внутренняя ошибка времени выполнения JavaScript: исходный код JavaScript, используемый внутри процесса начальной загрузки Node.js, выбросил ошибку при вызове функции начальной загрузки. Это происходит крайне редко и обычно возможно только во время разработки самой платформы Node.js.
• 12 Недопустимый аргумент отладки: были установлены опции --inspect и/или --inspect-brk, но выбранный номер порта оказался недопустимым или недоступным.
• 13 Незавершенный Top-Level Await: await был использован вне функции в коде верхнего уровня, но переданный Promise так и не завершился.
• 14 Сбой создания снапшота: Node.js был запущен для сборки стартового снапшота V8, и операция завершилась сбоем из-за несоблюдения определенных требований к состоянию приложения.
• >128 Завершение по сигналу: если Node.js получает фатальный сигнал, такой как SIGKILL или SIGHUP, его код выхода будет равен 128 плюс значение кода сигнала. Это стандартная практика POSIX, поскольку коды выхода определены как 7-битные целые числа, а выходы по сигналам устанавливают старший бит и содержат значение кода сигнала. Например, сигнал SIGABRT имеет значение 6, поэтому ожидаемым кодом выхода будет 128 + 6, то есть 134.