Процесс

Объект process является global, предоставляющим информацию о текущем процессе Node.js и контроль над ним. Как глобальный объект, он всегда доступен приложениям Node.js без использования require().

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

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

Событие: 'beforeExit'

Добавлен в: v0.11.12

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

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

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

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

Событие: 'disconnect'

Добавлен в: v0.7.7

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

Событие: 'exit'

Добавлен в: v0.1.7

code <целое>

Событие 'exit' срабатывает при завершении процесса Node.js по следующим причинам:

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

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

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

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

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

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

Событие: 'message'

Добавлен в: v0.5.10

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

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

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

Событие: 'multipleResolves'

Добавлен в: v10.12.0

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

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

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

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

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

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'

Добавлен в: v1.4.1

promise <Promise> — обещание, обработанное позже.

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

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

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

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

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

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

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

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

Событие: 'uncaughtException'

История

Версия	Изменения
v10.17.0	Добавлен аргумент `origin`.
v0.1.18	Добавлен в: v0.1.18

err <Ошибка> — необработанное исключение.
origin <строка> — указывает, происходит ли исключение от необработанного отклонения или от синхронных ошибок. Может быть 'uncaughtException' или 'unhandledRejection'.

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

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

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

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

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

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

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

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

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

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

Событие: 'unhandledRejection'

История

Версия	Изменения
v7.0.0	Обработка `Promise` отклонений устарела.
v6.6.0	Необработанные `Promise` отклонения теперь будут генерировать предупреждение процесса.
v1.4.1	Добавлено в: v1.4.1

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

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

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

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'

Добавлено в: v6.0.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// 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 будет немедленно завершён Windows примерно через 10 секунд. На платформах, отличных от Windows, стандартное поведение SIGHUP заключается в завершении Node.js, но после установки обработчика его стандартное поведение будет удалено.
'SIGTERM' не поддерживается на Windows, для него можно установить обработчик.
'SIGINT' из терминала поддерживается на всех платформах и обычно может быть сгенерирован с помощью <Ctrl>+C (хотя это может быть настраиваемо). Он не генерируется, когда режим терминала установлен в сыром режиме.
'SIGBREAK' подаётся на Windows при нажатии клавиши <Ctrl>+<Break>, на платформах, отличных от Windows, для него можно установить обработчик, но нет способа отправить или сгенерировать его.
'SIGWINCH' подаётся при изменении размера консоли. На Windows это произойдёт только при записи в консоль при перемещении курсора или при использовании читаемого tty в сыром режиме.
'SIGKILL' не может иметь обработчик, он немедленно завершит Node.js на всех платформах.
'SIGSTOP' не может иметь обработчик.
'SIGBUS', 'SIGFPE', 'SIGSEGV' и 'SIGILL', если они не были искусственно сгенерированы с помощью kill(2), оставляют процесс в состоянии, в котором небезопасно вызывать обработчики JS. Это может привести к зависанию процесса в бесконечном цикле, так как обработчики, установленные с помощью process.on() вызываются асинхронно и поэтому не могут исправить основную проблему.

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

process.abort()

Добавлено в: v0.7.0

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

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

process.allowedNodeEnvironmentFlags

Добавлено в: v10.10.0

<Множество>

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

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

Added in: v0.5.0

<строка>

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

Возможные значения в настоящее время: 'arm', 'arm64', 'ia32', 'mips', 'mipsel', 'ppc', 'ppc64', 's390', 's390x', 'x32', и 'x64'.

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

process.argv

Added in: v0.1.27

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

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

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

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

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

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

Выведет:

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

process.argv0

Added in: v6.4.0

<строка>

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

process.channel

Added in: v7.1.0

<объект>

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

process.chdir(directory)

Added in: v0.1.17

directory <строка>

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

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

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

process.config

Added in: v0.7.7

<объект>

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

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

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

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

process.connected

Added in: v0.7.2

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

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

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

process.cpuUsage([previousValue])

Added in: v6.1.0

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

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

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

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

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

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

process.cwd()

Added in: v0.1.8

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

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

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

process.debugPort

Added in: v0.7.2

<число>

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

process.debugPort = 5858;

process.disconnect()

Added in: v0.7.2

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

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

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

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

История

Версия	Изменения
v9.0.0	Добавлена поддержка аргумента `flags`.
v0.1.16	Добавлена в: v0.1.16

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

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

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

Если есть конкретные причины использовать process.dlopen() (например, для указания флагов dlopen), часто полезно использовать require.resolve() для поиска пути к модулю.

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

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

const os = require('os');
process.dlopen(module, require.resolve('binding'),
               os.constants.dlopen.RTLD_NOW);
module.exports.foo();

process.emitWarning(warning[, options])

Added in: v8.0.0

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

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

// Emit a warning with a code and additional detail.
process.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'.

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

Added in: v6.0.0

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

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

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

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

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

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

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

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

Будет выброшено исключение TypeError, если warning — это что-либо иное, чем строка или объект Error.

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

Ниже реализована дополнительная обработка, если предупреждение type имеет значение 'DeprecationWarning':

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

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

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

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

process.env

История

Версия	Изменения
v10.0.0	Неявное преобразование значения переменной в строку устарело.
v0.1.27	Добавлен в: v0.1.27

<Object>

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

Пример такого объекта:

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

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

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

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

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

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

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

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

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

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

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

process.env является только для чтения в потоках Worker.

process.execArgv

Added in: v0.7.7

<string[]>

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

$ node --harmony script.js --version

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

['--harmony']

И process.argv:

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

process.execPath

Added in: v0.1.100

<string>

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

'/usr/local/bin/node'

process.exit([code])

Added in: v0.1.13

code <integer> Код выхода. По умолчанию: 0.

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

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

process.exit(1);

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

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

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

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

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

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

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

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

Added in: v0.11.8

<целое>

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

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

process.getegid()

Added in: v2.0.0

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

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