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

Объект 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';

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

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

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

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 <Ошибка> Необработанное исключение.
• origin <строка> Указывает, возникло ли исключение из-за необработанного отторжения или из-за синхронных ошибок. Может быть либо '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 <Ошибка> | <любой> Объект, с помощью которого была отклонена (rejected) обещание (часто объект Error).
• 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 <Ошибка> Ключевые свойства предупреждения:
  • name <строка> Название предупреждения. По умолчанию: 'Warning'.
  • message <строка> Описание предупреждения, предоставленное системой.
  • stack <строка> Стек вызовов до места в коде, где было выведено предупреждение.

Событие '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.

Следующий пример демонстрирует предупреждение, которое отображается в 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'.

Событие: 'worker'

• worker <Поток_работы> Созданный поток <Поток_работы>.

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

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

См. метод 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.

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

События сигналов генерируются при получении процессом 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 для запуска отладчика debugger. Возможно установить обработчик, но это может помешать работе отладчика.
• '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 в сыром режиме.
• '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

• <Set>

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

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

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

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

Модули 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

• <string>

Архитектура процессора операционной системы, для которой был скомпилирован двоичный файл Node.js. Возможные значения: 'arm', 'arm64', 'ia32', 'mips','mipsel', 'ppc', 'ppc64', '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

• <string[]>

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

• <string>

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

$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0' 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_dtrace: 'false',
     node_use_openssl: 'true',
     node_shared_openssl: 'false',
     strict_aliasing: 'true',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
} copy

Свойство process.config не является только для чтения, и в экосистеме существуют модули, которые могут расширять, изменять или полностью заменять значение process.config.

Изменение свойства process.config или любого дочернего свойства объекта process.config устарело. Свойство process.config будет сделано только для чтения в будущей версии.

process.connected

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

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

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

process.constrainedMemory()

• <число> | <неопределённое>

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

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

process.execArgv

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

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

$ node --harmony script.js --version copy

Результатом будет process.execArgv:

['--harmony'] 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 <целое число> Код завершения. По умолчанию: 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

• <целое>

Число, которое будет кодом завершения процесса, когда процесс завершается корректно или завершается с помощью 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.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.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 для исходного tar-архива и tar-архива только заголовков.

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

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

{
  name: 'node',
  lts: 'Hydrogen',
  sourceUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz',
  headersUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz',
  libUrl: 'https://nodejs.org/download/release/v18.12.0/win-x64/node.lib'
} 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', отчёт записывается в 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', отчёт записывается в 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 <строка> | <число> Имя или идентификатор группы

Метод 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 <строка> | <число> Имя или идентификатор пользователя

Метод 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.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 до версии 0.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

• <string>

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

• <boolean>

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

process.umask()

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

process.umask(mask)

• mask <string> | <integer>

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

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

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

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

process.version

• <string>

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

• <Object>

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

Модули MJS

import { versions } from 'node:process';

console.log(versions);

Модули CJS

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

console.log(versions);

Сгенерирует объект, похожий на:

{ node: '11.13.0',
  v8: '7.0.276.38-node.18',
  uv: '1.27.0',
  zlib: '1.2.11',
  brotli: '1.0.7',
  ares: '1.15.0',
  modules: '67',
  nghttp2: '1.34.0',
  napi: '4',
  llhttp: '1.1.1',
  openssl: '1.1.1b',
  cldr: '34.0',
  icu: '63.1',
  tz: '2018e',
  unicode: '11.0' } copy

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

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

• 1 Необработанное критическое исключение: Произошло необработанное исключение, и оно не было обработано областью или обработчиком события 'uncaughtException'.
• 2: Неиспользуемый (зарезервирован Bash для неправильного использования встроенных функций)
• 3 Внутренняя ошибка синтаксического анализа JavaScript: Внутренний в коде Node.js код JavaScript при запуске вызвал синтаксическую ошибку. Это крайне редко и обычно может произойти только во время разработки самого Node.js.
• 4 Внутренняя ошибка вычисления JavaScript: Внутренний в коде Node.js код JavaScript при запуске не вернул значение функции при вычислении. Это крайне редко и обычно может произойти только во время разработки самого Node.js.
• 5 Критическая ошибка: Произошла критическая непреодолимая ошибка в V8. Обычно сообщение выводится в stderr с префиксом FATAL ERROR.
• 6 Нефункциональный внутренний обработчик исключений: Произошло необработанное исключение, но внутренняя функция обработки критических исключений каким-то образом была установлена не на функцию и не могла быть вызвана.
• 7 Ошибка во время выполнения внутреннего обработчика исключений: Произошло необработанное исключение, и сама внутренняя функция обработки критических исключений выбросила ошибку при попытке обработать ее. Это может произойти, например, если 'uncaughtException' или domain.on('error') обработчик выбросит ошибку.
• 8: Неиспользуемый. В предыдущих версиях Node.js код выхода 8 иногда указывал на необработанное исключение.
• 9 Неверный аргумент: Был указан неизвестный параметр или параметр, требующий значения, был предоставлен без значения.
• 10 Внутренняя ошибка во время выполнения JavaScript: Внутренний в коде Node.js код JavaScript при запуске выбросил ошибку при вызове функции запуска. Это крайне редко и обычно может произойти только во время разработки самого 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.