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

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

Событие: 'beforeExit'

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

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

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

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

Модули MJS

import process from 'node:process';

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

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

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

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

Модули CJS

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

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

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

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

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

Событие: 'disconnect'

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

Событие: 'exit'

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

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

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

Событие: 'message'

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

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

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

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

Событие: 'multipleResolves'

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

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

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

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

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

Модули MJS

import process from 'node:process';

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

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

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

Модули CJS

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

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

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

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

Событие: 'rejectionHandled'

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

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

Объект Promise ранее был бы сгенерирован в событии 'unhandledRejection' , но в ходе обработки приобрел обработчик отклонений.

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

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

Событие: 'uncaughtException'

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

Событие: 'uncaughtExceptionMonitor'

• err <Ошибка> Необработанное исключение.
• 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 <Ошибка> | <любой> Объект, с помощью которого была отклонена задача (обычно объект 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. В настоящее время нет возможности подавить определённые типы предупреждений, кроме предупреждений об устаревании. Чтобы подавить предупреждения об устаревании, используйте флаг --no-deprecation.

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

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

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

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

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

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

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

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

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

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

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

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

Нет строгих правил для типов предупреждений (как определено свойством name). Новые типы предупреждений могут быть добавлены в любое время. Некоторые из наиболее распространённых типов предупреждений:

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

Событие: 'worker'

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

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

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

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

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

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

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

Модули MJS

import process from 'node:process';

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

process.abort()

Метод process.abort() заставляет процесс Node.js немедленно завершиться и сгенерировать дамп памяти.

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

process.allowedNodeEnvironmentFlags

• <Набор>

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

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

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

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

Модули MJS

import { allowedNodeEnvironmentFlags } from 'node:process';

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

Модули CJS

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

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

Методы add(), clear(), и delete() из process.allowedNodeEnvironmentFlags ничего не делают и будут работать молча.

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

process.arch

• <строка>

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

Модули MJS

import { arch } from 'node:process';

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

Модули CJS

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

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

process.argv

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

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

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

Модули MJS

import { argv } from 'node:process';

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

Модули CJS

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

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

Запуск процесса Node.js как:

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

Выведет:

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

process.argv0

• <строка>

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

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

process.channel

• <Объект>

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

process.channel.ref()

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

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

process.channel.unref()

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

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

process.chdir(directory)

• directory <строка>

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

Модули MJS

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

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

Модули CJS

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

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

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

process.config

• <Объект>

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

Пример возможного вывода:

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

process.connected

• <булево>

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

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

process.constrainedMemory()

• <число>

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

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

process.availableMemory()

• <число>

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

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

process.cpuUsage([previousValue])

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

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

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

Модули MJS

import { cpuUsage } from 'node:process';

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

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

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

Модули CJS

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

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

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

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

process.cwd()

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

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

Модули MJS

import { cwd } from 'node:process';

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

Модули CJS

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

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

process.debugPort

• <число>

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

Модули MJS

import process from 'node:process';

process.debugPort = 5858;

Модули CJS

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

process.debugPort = 5858;

process.disconnect()

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

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

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

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

• module <Объект>
• filename <строка>
• flags <os.constants.dlopen> По умолчанию: os.constants.dlopen.RTLD_LAZY

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

process.emitWarning(warning[, options])

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

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

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { emitWarning } from 'node:process';

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

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

Модули CJS

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

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

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

Выбрасывается TypeError, если warning является чем-то кроме строки или объекта Error.

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

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

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

Избегание дублирующих предупреждений

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

Модули MJS

import { emitWarning } from 'node:process';

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

Модули CJS

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

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

process.env

• <Объект>

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

Пример этого объекта выглядит так:

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

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

Модули MJS

import { env } from 'node:process';

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

Модули CJS

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

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

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

process.execArgv

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

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

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

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

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

И process.argv:

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

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

process.execPath

• <строка>

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

'/usr/local/bin/node' copy

process.exit([code])

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

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

Для выхода с кодом 'ошибка':

Модули MJS

import { exit } from 'node:process';

exit(1);

Модули CJS

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

exit(1);

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

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

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

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

Модули MJS

import { exit } from 'node:process';

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

Модули CJS

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

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

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

process.exitCode

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

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

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

process.getActiveResourcesInfo()

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

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

Модули MJS

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

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

Модули CJS

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

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

process.getBuiltinModule(id)

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

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

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

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

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

process.getegid()

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

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

• Returns: <boolean>

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

process.hrtime([time])

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

Это устаревшая версия 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()

• Returns: <bigint>

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

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

Модули MJS

import { hrtime } from 'node:process';

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

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

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

Модули CJS

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

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

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

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

process.initgroups(user, extraGroup)

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

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

Обращайтесь с осторожностью при снижении привилегий:

Модули MJS

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

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

Модули CJS

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

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

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

process.kill(pid[, signal])

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

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

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

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

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

Модули MJS

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

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

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

kill(process.pid, 'SIGHUP');

Модули CJS

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

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

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

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

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

process.loadEnvFile(path)

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

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

Модули CJS

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

Модули MJS

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

process.mainModule

• <Объект>

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

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

process.memoryUsage()

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

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

MJS модули

import { memoryUsage } from 'node:process';

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

CJS модули

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

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

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

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

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

process.memoryUsage.rss()

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

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

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

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

MJS модули

import { memoryUsage } from 'node:process';

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

CJS модули

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

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

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

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

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

MJS модули

import { nextTick } from 'node:process';

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

CJS модули

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

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

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

MJS модули

import { nextTick } from 'node:process';

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

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

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

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

CJS модули

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

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

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

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

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

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

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

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

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

const maybeTrue = Math.random() > 0.5;

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

bar(); copy

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

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

MJS модули

import { nextTick } from 'node:process';

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

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

CJS модули

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

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

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

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

API queueMicrotask() — это альтернатива process.nextTick(), которая также откладывает выполнение функции, используя ту же очередь микрозадач, используемую для выполнения обработчиков then, catch и finally разрешённых промисов. В Node.js каждый раз, когда очередь «следующего тика» очищается, очередь микрозадач очищается сразу после этого.

MJS модули

import { nextTick } from 'node:process';

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

CJS модули

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

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

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

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

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

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

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

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

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

process.noDeprecation

• <булево>

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

process.permission

• <Объект>

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

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

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

• scope <строка>
• reference <строка>
• Возвращает: <булево>

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

Reference имеет значение, основанное на заданном scope. Например, reference, когда scope — файловая система, означает файлы и папки.

Доступные scope:

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

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

process.pid

• <целое>

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

MJS модули

import { pid } from 'node:process';

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

CJS модули

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

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

process.platform

• <строка>

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

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

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

MJS модули

import { platform } from 'node:process';

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

CJS модули

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

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

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

process.ppid

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

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

MJS модули

import { ppid } from 'node:process';

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

CJS модули

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

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

process.release

• <Объект>

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

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

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

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

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

process.report

• <Объект>

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

process.report.compact

• <булево>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.directory

• <строка>

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

MJS модули

import { report } from 'node:process';

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

CJS модули

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

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

process.report.filename

• <строка>

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

Если значение process.report.filename установлено в 'stdout' или 'stderr', отчёт будет записан в стандартный поток вывода 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 <строка> | <число> Имя или ID группы

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.seteuid(id)

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.setgroups(groups)

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

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.setuid(id)

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

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

Модули MJS

import process from 'node:process';

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

Модули CJS

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

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

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

process.setSourceMapsEnabled(val)

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

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

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

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

process.setUncaughtExceptionCaptureCallback(fn)

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

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

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

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

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

process.sourceMapsEnabled

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

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

process.stderr

• <Поток>

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

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

process.stderr.fd

• <число>

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

process.stdin

• <Поток>

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

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

Как поток «дуплекс», 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 (дескриптор файла 1). Это net.Socket (который является потоком типа «дуплекс»), если дескриптор файла 1 относится к файлу, в противном случае это поток типа «только запись».

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

Модули MJS

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

stdin.pipe(stdout);

Модули CJS

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

stdin.pipe(stdout);

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

process.stdout.fd

• <число>

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

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

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

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

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

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

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

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

Например:

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

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

process.throwDeprecation

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

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

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

process.title

• <строка>

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

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

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

process.traceDeprecation

• <булево>

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

process.umask()

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

process.umask(mask)

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

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

MJS модули

import { umask } from 'node:process';

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

CJS модули

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

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

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

process.uptime()

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

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

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

process.version

• <строка>

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

MJS модули

import { version } from 'node:process';

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

CJS модули

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

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

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

process.versions

• <Объект>

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

MJS модули

import { versions } from 'node:process';

console.log(versions);

CJS модули

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

console.log(versions);

Сгенерирует объект, подобный:

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

Коды выхода

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

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