Обработка событий

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

Событие: 'beforeExit'

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

Обработчик вызывается с значением process.exitCode в качестве единственного аргумента.

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

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

MJS модули

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

CJS модули

const process = require('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

Событие: 'disconnect'

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

Событие: 'exit'

• code <целое число>

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

• Явного вызова метода process.exit();
• Цикл событий Node.js больше не имеет дополнительных задач для выполнения.

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

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

MJS модули

import process from 'node:process';

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

CJS модули

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

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

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

MJS модули

import process from 'node:process';

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

CJS модули

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

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

Событие: 'message'

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

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

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

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

Событие: 'multipleResolves'

• type <строка> Тип разрешения. Один из 'resolve' или 'reject'.
• promise <Promise> Promise, который был разрешен или отклонен более одного раза.
• value <любое> Значение, с помощью которого promise был разрешен или отклонен после первоначального разрешения.

Событие 'multipleResolves' генерируется всякий раз, когда Promise был:

• Разрешен более одного раза.
• Отклонен более одного раза.
• Отклонен после разрешения.
• Разрешен после отклонения.

Это полезно для отслеживания возможных ошибок в приложении при использовании конструктора Promise, так как несколько разрешений молча игнорируются. Однако появление этого события не обязательно указывает на ошибку. Например, Promise.race() может сгенерировать событие 'multipleResolves'.

Из-за ненадежности события в таких случаях, как в примере с Promise.race(), оно устарело.

MJS модули

import process from 'node:process';

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason);
  setImmediate(() => process.exit(1));
});

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call');
      resolve('Swallowed resolve');
      reject(new Error('Swallowed reject'));
    });
  } catch {
    throw new Error('Failed');
  }
}

main().then(console.log);
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First call

CJS модули

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

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason);
  setImmediate(() => process.exit(1));
});

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call');
      resolve('Swallowed resolve');
      reject(new Error('Swallowed reject'));
    });
  } catch {
    throw new Error('Failed');
  }
}

main().then(console.log);
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First call

Событие: 'rejectionHandled'

• promise <Promise> Обработанный promise.

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

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

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

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

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

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

MJS модули

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);
});

CJS модули

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

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

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

Событие: 'uncaughtException'

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

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

MJS модули

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.');

Модули CJS

const process = require('node:process');
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'.

Модули MJS

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

Модули CJS

const process = require('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

Событие: 'unhandledRejection'

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

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

Модули MJS

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()`

Модули CJS

const process = require('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()`

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

Модули MJS

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

Модули CJS

const process = require('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

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

Событие: 'warning'

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

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

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

Модули MJS

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
});

Модули CJS

const process = require('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
});

По умолчанию 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 copy

В отличие от этого, в следующем примере отключается стандартный вывод предупреждений и добавляется пользовательский обработчик для события '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! copy

Флаг командной строки --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' — указывает на то, что числовое значение, которое не может уместиться в 32-битном знаковом целом числе, было передано функциям setTimeout() или setInterval().
• 'UnsupportedWarning' — указывает на использование неподдерживаемого параметра или функции, которая будет проигнорирована, а не рассматриваться как ошибка. Пример — использование сообщения состояния HTTP в ответ при использовании совместимого API HTTP/2.

Событие: 'worker'

• worker <Worker> Созданная нить <Worker>.

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

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

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

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

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

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

Модули MJS

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);

Модули CJS

const process = require('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);

• 'SIGUSR1' зарезервирован в Node.js для запуска отладчика. Отладчик можно использовать, но это может повлиять на работу отладчика.
• 'SIGTERM' и 'SIGINT' имеют обработчики по умолчанию на платформах, отличных от Windows, которые сбрасывают режим терминала перед завершением с кодом 128 + signal number. Если для одного из этих сигналов установлен обработчик, его поведение по умолчанию будет удалено (Node.js больше не завершится).
• 'SIGPIPE' по умолчанию игнорируется. Для него можно установить обработчик.
• 'SIGHUP' генерируется в Windows при закрытии окна консоли, а также на других платформах при различных аналогичных условиях. См. signal(7). Для него можно установить обработчик, однако Node.js будет безусловно завершен через 10 секунд 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 немедленно завершиться и сгенерировать дамп памяти.

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

process.allowedNodeEnvironmentFlags

• <Набор>

Свойство 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, будут содержать подчёркивания вместо не ведущих дефисов:

Модули MJS

import { allowedNodeEnvironmentFlags } from 'node:process';

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

Модули CJS

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

• <строка>

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

Модули MJS

import { arch } from 'node:process';

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

Модули CJS

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

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

process.argv

• <массив строк>

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

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

Модули MJS

import { argv } from 'node:process';

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

Модули CJS

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 copy

Выведет:

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

process.argv0

• <строка>

Свойство 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' copy

process.channel

• <Объект>

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

process.channel.ref()

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

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

process.channel.unref()

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

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

process.chdir(directory)

• directory <строка>

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

Модули MJS

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}`);
}

Модули CJS

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

• <Объект>

Свойство 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',
     strict_aliasing: 'true',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
} copy

process.connected

• <boolean>

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

После того, как process.connected false, отправить сообщения по каналу IPC с помощью process.send() больше невозможно.

process.constrainedMemory()

• <число>

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

См. uv_get_constrained_memory для получения дополнительной информации.

process.availableMemory()

• <число>

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

См. uv_get_available_memory для получения дополнительной информации.

process.cpuUsage([previousValue])

• previousValue <Объект> Предыдущее значение, возвращённое при вызове process.cpuUsage()
• Возвращает: <Объект>
  • user <целое>
  • system <целое>

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

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

МОДУЛИ MJS

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 }

МОДУЛИ CJS

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()

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

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

МОДУЛИ MJS

import { cwd } from 'node:process';

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

МОДУЛИ CJS

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

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

process.debugPort

• <число>

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

МОДУЛИ MJS

import process from 'node:process';

process.debugPort = 5858;

МОДУЛИ CJS

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

process.debugPort = 5858;

process.disconnect()

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

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

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

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

• module <Объект>
• filename <строка>
• 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. В этом примере предполагается, что константа доступна.

МОДУЛИ MJS

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();

МОДУЛИ CJS

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 <строка> | <Ошибка> Предупреждение для вывода.
• options <Объект>
  • type <строка> Когда warning является String, type — имя, используемое для типа выводимого предупреждения. По умолчанию: 'Warning'.
  • code <строка> Уникальный идентификатор экземпляра предупреждения, который выводится.
  • ctor <Функция> Когда warning является String, ctor — необязательная функция, используемая для ограничения генерируемого трассировки стека. По умолчанию: process.emitWarning.
  • detail <строка> Дополнительный текст для включения в ошибку.

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

Модули MJS

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

Модули CJS

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'.

Модули MJS

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'
});

Модули CJS

const process = require('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'
});

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

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

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

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);
});

Модули CJS

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

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 будут проигнорированы):

Модули MJS

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!

Модули CJS

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() за логическим значением.

Модули MJS

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

Модули CJS

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

• <Объект>

Свойство 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'
} copy

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

• <массив строк>

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

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

Результат process.execArgv:

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

И process.argv:

['/usr/local/bin/node', 'script.js', '--version'] copy

Обратитесь к Worker для подробного поведения потоков-рабочих с этим свойством.

process.execPath

• <строка>

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

'/usr/local/bin/node' copy

process.exit([code])

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

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

Для завершения с кодом 'ошибка':

Модули MJS

import { exit } from 'node:process';

exit(1);

Модули CJS

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:

Модули MJS

import { exit } from 'node:process';

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

Модули CJS

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 и позволить процессу выйти естественным путём, избегая планирования дополнительных задач для цикла событий:

Модули MJS

import process from 'node:process';

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

Модули CJS

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

// 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

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

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

Указание кода для process.exit(code) переопределит любое предыдущее значение process.exitCode.

process.getActiveResourcesInfo()

• Возвращает: <массив строк>

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

Модули MJS

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' ]

Модули CJS

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.getegid()

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.geteuid()

• Возвращает: <Объект>

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.getgid()

• Возвращает: <Объект>

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.getgroups()

• Возвращает: <массив целых чисел>

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.getuid()

• Возвращает: <целое число>

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.hasUncaughtExceptionCaptureCallback()

• Возвращает: <логическое значение>

Указывает, был ли установлен обратный вызов с помощью process.setUncaughtExceptionCaptureCallback().

process.hrtime([time])

• time <массив целых чисел> Результат предыдущего вызова process.hrtime()
• Возвращает: <массив целых чисел>

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

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

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

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

MJS модули

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);

CJS модули

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>

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

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

MJS модули

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);

CJS модули

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 <строка> | <число> Имя пользователя или числовой идентификатор.
• extraGroup <строка> | <число> Имя группы или числовой идентификатор.

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

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

MJS модули

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 ]

CJS модули

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

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

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

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

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

MJS модули

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');

CJS модули

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

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

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

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

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

process.loadEnvFile(path)

• path <строка> | <URL> | <Буфер> | <неопределено>. По умолчанию: './.env'

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

CJS модули

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

MJS модули

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

process.mainModule

• <Объект>

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

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

process.memoryUsage()

• Возвращает: <Объект>
  • rss <целое число>
  • heapTotal <целое число>
  • heapUsed <целое число>
  • external <целое число>
  • arrayBuffers <целое число>

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

MJS модули

import { memoryUsage } from 'node:process';

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

CJS модули

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, Размер резидентного набора, — это объём памяти, занимаемый в оперативной памяти (это подмножество выделенной памяти) процессом, включая все объекты C++ и JavaScript, а также код.
• arrayBuffers относится к памяти, выделенной для ArrayBuffer и SharedArrayBuffer, включая все объекты Node.js Buffer. Это также включено в значение external. Когда Node.js используется как встроенная библиотека, это значение может быть 0, так как выделения для ArrayBuffer в этом случае могут не отслеживаться.

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

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

process.memoryUsage.rss()

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

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

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

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

Модули MJS

import { memoryUsage } from 'node:process';

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

Модули CJS

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

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

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

• callback <Функция>
• ...args <любой тип> Дополнительные аргументы для передачи при вызове callback

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

Модули MJS

import { nextTick } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

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.

Модули CJS

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);
} copy

Этот API небезопасен, потому что в следующем случае:

const maybeTrue = Math.random() > 0.5;

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

bar(); copy

Непонятно, какой метод foo() или bar() будет вызван первым.

Следующий подход намного лучше:

Модули MJS

import { nextTick } from 'node:process';

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

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

Модули CJS

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(), которая также откладывает выполнение функции, используя ту же очередь микробзадач, что и для обработки then, catch и finally обработчиков разрешенных промисов. В Node.js каждый раз, когда обрабатывается очередь "следующей итерации", очередь микробзадач обрабатывается сразу после.

Модули MJS

import { nextTick } from 'node:process';

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
nextTick(() => console.log(1));
// Output:
// 1
// 2
// 3

Модули CJS

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

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
nextTick(() => console.log(1));
// Output:
// 1
// 2
// 3

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

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

Одно важное отличие между двумя 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 copy

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

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

process.noDeprecation

• <логическое>

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

process.permission

• <Объект>

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

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

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

• scope <строка>
• reference <строка>
• Возвращает: <логическое>

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

Ссылка имеет значение, основанное на предоставленном объёме. Например, если объем — Файловая система, ссылка относится к файлам и папкам.

Доступные объёмы:

• fs - Вся файловая система
• fs.read - Операции чтения файловой системы
• fs.write - Операции записи файловой системы
• child - Операции запуска дочерних процессов
• worker - Операция запуска потоков-работников

// 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'); copy

process.pid

• <целое>

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

Модули MJS

import { pid } from 'node:process';

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

Модули CJS

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

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

process.platform

• <строка>

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

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

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

Модули MJS

import { platform } from 'node:process';

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

Модули CJS

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

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

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

process.ppid

• <целое>

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

Модули MJS

import { ppid } from 'node:process';

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

Модули CJS

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

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

process.release

• <Объект>

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

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

• name <строка> Значение, которое всегда будет 'node'.
• sourceUrl <строка> абсолютный URL, указывающий на файл .tar.gz, содержащий исходный код текущей версии.
• headersUrl<строка> абсолютный URL, указывающий на файл .tar.gz, содержащий только исходные заголовочные файлы текущей версии. Этот файл значительно меньше полного исходного файла и может использоваться для компиляции нативных дополнений Node.js.
• libUrl <строка> | <неопределено> абсолютный URL, указывающий на файл node.lib, соответствующий архитектуре и версии текущей версии. Этот файл используется для компиляции нативных дополнений Node.js. Это свойство присутствует только в Windows-версиях Node.js и отсутствует на всех других платформах.
• lts <строка> | <неопределено> строковая метка, определяющая метку 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'
} copy

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

process.report

• <Объект>

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

process.report.compact

• <логическое значение>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.directory

• <строка>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.filename

• <строка>

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

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.getReport([err])

• err <Ошибка> Специальная ошибка, используемая для записи стека вызовов JavaScript.
• Возвращает: <Объект>

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

MJS модули

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');

CJS модули

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

• <логическое значение>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.reportOnSignal

• <логическое значение>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.reportOnUncaughtException

• <логическое значение>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.signal

• <строка>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

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

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

• err <Ошибка> Специальная ошибка, используемая для записи стека вызовов JavaScript.

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

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

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

MJS модули

import { report } from 'node:process';

report.writeReport();

CJS модули

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

report.writeReport();

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

process.resourceUsage()

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

Модули MJS

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
  }
*/

Модули CJS

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 <Объект>
• sendHandle <net.Сервер> | <net.Сокет>
• options <Объект> используется для параметризации отправки определенных типов дескрипторов. options поддерживает следующие свойства:
  • keepOpen <логическое значение> Значение, которое можно использовать при передаче экземпляров net.Socket. Когда true, сокет остается открытым в процессе отправки. По умолчанию: false.
• callback <Функция>
• Returns: <логическое значение>

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

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

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

process.setegid(id)

• id <строка> | <число> Имя или ID группы

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

Модули MJS

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}`);
  }
}

Модули CJS

const process = require('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}`);
  }
}

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

process.seteuid(id)

• id <строка> | <число> Имя или ID пользователя

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

Модули MJS

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}`);
  }
}

Модули CJS

const process = require('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}`);
  }
}

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

process.setgid(id)

• id <строка> | <число> Имя или ID группы

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

Модули MJS

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}`);
  }
}

Модули CJS

const process = require('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}`);
  }
}

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

process.setgroups(groups)

• groups <массив целых чисел>

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

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

Модули MJS

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}`);
  }
}

Модули CJS

const process = require('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}`);
  }
}

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

process.setuid(id)

• id <целое> | <строка>

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

Модули MJS

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}`);
  }
}

Модули CJS

const process = require('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}`);
  }
}

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

process.setSourceMapsEnabled(val)

• val <логическое>

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

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

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

process.setUncaughtExceptionCaptureCallback(fn)

• fn <Функция> | <null>

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

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

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

Использование этой функции несовместимо с использованием устаревшего встроенного модуля domain.

process.sourceMapsEnabled

• <логическое>

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

process.stderr

• <Поток>

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

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

process.stderr.fd

• <число>

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

process.stdin

• <Поток>

Свойство 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

• <число>

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

process.stdout

• <Поток>

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

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

Модули MJS

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

stdin.pipe(stdout);

Модули CJS

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

stdin.pipe(stdout);

process.stdout отличается от других потоков Node.js важными особенностями. См. примечание о вводе-выводе процесса для получения дополнительной информации.

process.stdout.fd

• <число>

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

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

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

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

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

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

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

Чтобы проверить, подключен ли поток к контексту 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 copy

См. документацию TTY для получения дополнительной информации.

process.throwDeprecation

• <логическое>

Начальное значение 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' } copy

process.title

• <строка>

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

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

Присвоение значения process.title может не привести к точному отображению названия в приложениях управления процессами, таких как macOS Activity Monitor или Windows Services Manager.

process.traceDeprecation

• <логическое значение>

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

process.umask()

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

process.umask(mask)

• mask <строка> | <целое число>

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

MJS модули

import { umask } from 'node:process';

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

CJS модули

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.uptime()

• Возвращает: <число>

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

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

process.version

• <строка>

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

MJS модули

import { version } from 'node:process';

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

CJS модули

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

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

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

process.versions

• <Объект>

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

MJS модули

import { versions } from 'node:process';

console.log(versions);

CJS модули

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

console.log(versions);

Сгенерирует объект, аналогичный:

{ node: '23.0.0',
  acorn: '8.11.3',
  ada: '2.7.8',
  ares: '1.28.1',
  base64: '0.5.2',
  brotli: '1.1.0',
  cjs_module_lexer: '1.2.2',
  cldr: '45.0',
  icu: '75.1',
  llhttp: '9.2.1',
  modules: '127',
  napi: '9',
  nghttp2: '1.61.0',
  nghttp3: '0.7.0',
  ngtcp2: '1.3.0',
  openssl: '3.0.13+quic',
  simdjson: '3.8.0',
  simdutf: '5.2.4',
  tz: '2024a',
  undici: '6.13.0',
  unicode: '15.1',
  uv: '1.48.0',
  uvwasi: '0.0.20',
  v8: '12.4.254.14-node.11',
  zlib: '1.3.0.1-motley-7d77fb7' } copy

Коды завершения

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 Незавершенный верхнеуровневый await: await был использован вне функции в верхнеуровневом коде, но переданный Promise никогда не был разрешен.
• 14 Ошибка создания снимка: Node.js был запущен для создания снимка запуска V8, но он завершился ошибкой из-за того, что определённые требования к состоянию приложения не были выполнены.
• >128 Завершение по сигналу: Если Node.js получит фатальный сигнал, такой как SIGKILL или SIGHUP, код завершения будет 128 плюс значение кода сигнала. Это стандартная практика POSIX, так как коды завершения определены как 7-битовые целые числа, а сигналы завершения устанавливают старший бит, а затем содержат значение кода сигнала. Например, сигнал SIGABRT имеет значение 6, поэтому ожидаемый код завершения будет 128 + 6, или 134.