Процесс

Исходный код: lib/process.js

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

ESM

import process from 'node:process'

CJS

const process = require('node:process')

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

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

Событие: 'beforeExit'

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

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

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

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

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

ESM

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'

Добавлен в: 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().

ESM

import process from 'node:process'

process.on('exit', code => {
  console.log(`Завершение с кодом: ${code}`)
})

CJS

const process = require('node:process')

process.on('exit', code => {
  console.log(`Завершение с кодом: ${code}`)
})

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

ESM

import process from 'node:process'

process.on('exit', code => {
  setTimeout(() => {
    console.log('Это не будет выполнено')
  }, 0)
})

CJS

const process = require('node:process')

process.on('exit', code => {
  setTimeout(() => {
    console.log('Это не будет выполнено')
  }, 0)
})

Событие: 'message'

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

• message <Object> | <boolean> | <number> | <string> | <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'

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

Устарело с: v17.6.0, v16.15.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело

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

Событие 'multipleResolves' генерируется, если Promise:

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

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

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

ESM

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'

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

• promise <Promise> Обещание, обработка которого произошла позднее.

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

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

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

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

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

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

ESM

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

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

Событие: 'workerMessage'

Добавлено в: v22.5.0

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

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

Событие: 'uncaughtException'

[История]

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

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

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

ESM

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)

// Намеренно вызываем исключение, но не перехватываем его.
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)

// Намеренно вызываем исключение, но не перехватываем его.
nonexistentFunc()
console.log('This will not run.')

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

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

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

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

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

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

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

Событие: 'uncaughtExceptionMonitor'

Добавлено в: v13.7.0, v12.17.0

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

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

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

ESM

import process from 'node:process'

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

// Намеренно вызываем исключение, но не перехватываем его.
nonexistentFunc()
// Node.js всё равно завершается аварийно

CJS

const process = require('node:process')

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

// Намеренно вызываем исключение, но не перехватываем его.
nonexistentFunc()
// Node.js всё равно завершается аварийно

Событие: 'unhandledRejection'

[История]

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

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

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

ESM

import process from 'node:process'

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason)
  // Специфическое для приложения логирование, генерация ошибки или другая логика здесь
})

somePromise.then(res => {
  return reportToUser(JSON.pasre(res)) // Обратите внимание на опечатку (`pasre`)
}) // Нет `.catch()` или `.then()`

CJS

const process = require('node:process')

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason)
  // Специфическое для приложения логирование, генерация ошибки или другая логика здесь
})

somePromise.then(res => {
  return reportToUser(JSON.pasre(res)) // Обратите внимание на опечатку (`pasre`)
}) // Нет `.catch()` или `.then()`

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

ESM

import process from 'node:process'

function SomeResource() {
  // Первоначально устанавливаем статус загрузки в отклоненный promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'))
}

const resource = new SomeResource()
// нет .catch или .then на resource.loaded хотя бы в течение одного цикла

CJS

const process = require('node:process')

function SomeResource() {
  // Первоначально устанавливаем статус загрузки в отклоненный promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'))
}

const resource = new SomeResource()
// нет .catch или .then на resource.loaded хотя бы в течение одного цикла

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

Событие: 'warning'

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

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

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

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

ESM

import process from 'node:process'

process.on('warning', warning => {
  console.warn(warning.name) // Вывести имя предупреждения
  console.warn(warning.message) // Вывести сообщение предупреждения
  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.stack) // Вывести трассировку стека
})

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

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

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Возможно, обнаружена утечка памяти EventEmitter. Добавлено 2 обработчика foo. Используйте emitter.setMaxListeners(), чтобы увеличить лимит

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

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Не делайте этого!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Не делайте этого!

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

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

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

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

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

Вывод пользовательских предупреждений

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

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

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

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

Событие: 'worker'

Добавлено в: v16.2.0, v14.18.0

• worker <Worker> Созданный <Worker>.

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

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

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

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

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

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

ESM

import process from 'node:process'

// Начинаем чтение из stdin, чтобы процесс не завершился.
process.stdin.resume()

process.on('SIGINT', () => {
  console.log('Получен SIGINT. Нажмите Control-D для выхода.')
})

// Использование одной функции для обработки нескольких сигналов
function handle(signal) {
  console.log(`Получен ${signal}`)
}

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

CJS

const process = require('node:process')

// Начинаем чтение из stdin, чтобы процесс не завершился.
process.stdin.resume()

process.on('SIGINT', () => {
  console.log('Получен SIGINT. Нажмите Control-D для выхода.')
})

// Использование одной функции для обработки нескольких сигналов
function handle(signal) {
  console.log(`Получен ${signal}`)
}

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

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

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

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

process.abort()

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

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

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

process.allowedNodeEnvironmentFlags

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

• <Set>

Свойство process.allowedNodeEnvironmentFlags представляет собой специальное, доступное только для чтения множество флагов, допустимых в переменной среды 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, будут содержать подчеркивания вместо нелидирующих тире:

ESM

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

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

• <string>

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

ESM

import { arch } from 'node:process'

console.log(`Архитектура этого процессора: ${arch}`)

CJS

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

console.log(`Архитектура этого процессора: ${arch}`)

process.argv

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

• <string[]>

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

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

ESM

import { argv } from 'node:process'

// вывод process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`)
})

CJS

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

// вывод process.argv
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

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

• <string>

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

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

process.channel

[История]

Версия	Изменения
v14.0.0	Объект больше не случайно предоставляет доступ к нативным C++ привязкам.
v7.1.0	Добавлено в: v7.1.0

• <Объект>

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

process.channel.ref()

Добавлен в: v7.1.0

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

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

process.channel.unref()

Добавлен в: v7.1.0

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

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

process.chdir(directory)

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

• directory <строка>

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

ESM

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

console.log(`Исходный каталог: ${cwd()}`)
try {
  chdir('/tmp')
  console.log(`Новый каталог: ${cwd()}`)
} catch (err) {
  console.error(`chdir: ${err}`)
}

CJS

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

console.log(`Исходный каталог: ${cwd()}`)
try {
  chdir('/tmp')
  console.log(`Новый каталог: ${cwd()}`)
} catch (err) {
  console.error(`chdir: ${err}`)
}

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

process.config

[История]

Версия	Изменения
v19.0.0	Объект process.config теперь заморожен.
v16.0.0	Изменение process.config устарело.
v0.7.7	Добавлено в: 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: 5,
     node_install_npm: 'true',
     node_prefix: '',
     node_shared_cares: 'false',
     node_shared_http_parser: 'false',
     node_shared_libuv: 'false',
     node_shared_zlib: 'false',
     node_use_openssl: 'true',
     node_shared_openssl: 'false',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
}

process.connected

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

• <булево>

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

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

process.constrainedMemory()

[История]

Версия	Изменения
v22.0.0, v20.13.0	Выравнивание возвращаемого значения с uv_get_constrained_memory.
v19.6.0, v18.15.0	Добавлено в: v19.6.0, v18.15.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

• <число>

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

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

process.availableMemory()

Добавлено в: v22.0.0, v20.13.0

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1 - Экспериментально

• <число>

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

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

process.cpuUsage([previousValue])

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

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

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

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

ESM

import { cpuUsage } from 'node:process'

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

// Занять ЦП на 500 миллисекунд
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 }

// Занять ЦП на 500 миллисекунд
const now = Date.now()
while (Date.now() - now < 500);

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

process.cwd()

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

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

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

ESM

import { cwd } from 'node:process'

console.log(`Текущий каталог: ${cwd()}`)

CJS

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

console.log(`Текущий каталог: ${cwd()}`)

process.debugPort

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

• <number>

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

ESM

import process from 'node:process'

process.debugPort = 5858

CJS

const process = require('node:process')

process.debugPort = 5858

process.disconnect()

Добавлено в: 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 <Object>
• filename <string>
• flags <os.constants.dlopen> По умолчанию: os.constants.dlopen.RTLD_LAZY

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

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

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

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

ESM

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

Добавлено в: 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'.

ESM

import { emitWarning } from 'node:process'

// Вывод предупреждения с кодом и дополнительными сведениями.
emitWarning('Что-то случилось!', {
  code: 'MY_WARNING',
  detail: 'Это дополнительная информация',
})
// Выводит:
// (node:56338) [MY_WARNING] Warning: Что-то случилось!
// Это дополнительная информация

CJS

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

// Вывод предупреждения с кодом и дополнительными сведениями.
emitWarning('Что-то случилось!', {
  code: 'MY_WARNING',
  detail: 'Это дополнительная информация',
})
// Выводит:
// (node:56338) [MY_WARNING] Warning: Что-то случилось!
// Это дополнительная информация

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

ESM

import process from 'node:process'

process.on('warning', warning => {
  console.warn(warning.name) // 'Warning'
  console.warn(warning.message) // 'Что-то случилось!'
  console.warn(warning.code) // 'MY_WARNING'
  console.warn(warning.stack) // Трассировка стека
  console.warn(warning.detail) // 'Это дополнительная информация'
})

CJS

const process = require('node:process')

process.on('warning', warning => {
  console.warn(warning.name) // 'Warning'
  console.warn(warning.message) // 'Что-то случилось!'
  console.warn(warning.code) // 'MY_WARNING'
  console.warn(warning.stack) // Трассировка стека
  console.warn(warning.detail) // 'Это дополнительная информация'
})

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

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

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

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

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

ESM

import { emitWarning } from 'node:process'

// Вывод предупреждения с использованием строки.
emitWarning('Something happened!')
// Выводит: (node: 56338) Warning: Something happened!

CJS

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

// Вывод предупреждения с использованием строки.
emitWarning('Something happened!')
// Выводит: (node: 56338) Warning: Something happened!

ESM

import { emitWarning } from 'node:process'

// Вывод предупреждения с использованием строки и типа.
emitWarning('Something Happened!', 'CustomWarning')
// Выводит: (node:56338) CustomWarning: Something Happened!

CJS

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

// Вывод предупреждения с использованием строки и типа.
emitWarning('Something Happened!', 'CustomWarning')
// Выводит: (node:56338) CustomWarning: Something Happened!

ESM

import { emitWarning } from 'node:process'

emitWarning('Something happened!', 'CustomWarning', 'WARN001')
// Выводит: (node:56338) [WARN001] CustomWarning: Something happened!

CJS

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

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001')
// Выводит: (node:56338) [WARN001] CustomWarning: Something happened!

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

ESM

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

ESM

import { emitWarning } from 'node:process'

// Вывод предупреждения с использованием объекта Error.
const myWarning = new Error('Something happened!')
// Использование свойства имени Error для указания имени типа
myWarning.name = 'CustomWarning'
myWarning.code = 'WARN001'

emitWarning(myWarning)
// Выводит: (node:56338) [WARN001] CustomWarning: Something happened!

CJS

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

// Вывод предупреждения с использованием объекта Error.
const myWarning = new Error('Something happened!')
// Использование свойства имени Error для указания имени типа
myWarning.name = 'CustomWarning'
myWarning.code = 'WARN001'

emitWarning(myWarning)
// Выводит: (node:56338) [WARN001] CustomWarning: Something happened!

Если warning является чем-либо отличным от строки или объекта Error, генерируется исключение TypeError.

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

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

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

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

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

ESM

import { emitWarning } from 'node:process'

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true
    emitWarning('Only warn once!')
  }
}
emitMyWarning()
// Выводит: (node: 56339) Warning: Only warn once!
emitMyWarning()
// Ничего не выводит

CJS

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

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true
    emitWarning('Only warn once!')
  }
}
emitMyWarning()
// Выводит: (node: 56339) Warning: Only warn once!
emitMyWarning()
// Ничего не выводит

process.env

[История]

Версия	Изменения
v11.14.0	Рабочие потоки теперь будут использовать копию process.env родительского потока по умолчанию, настраиваемое через опцию env конструктора Worker.
v10.0.0	Неявное преобразование значения переменной в строку устарело.
v0.1.27	Добавлено в: v0.1.27

• <Объект>

Свойство 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 или (если явно не запрошено) в других потоках Worker. Другими словами, следующий пример не будет работать:

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

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

ESM

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 может возникнуть ошибка, если значение не является строкой, числом или булевым значением.

ESM

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.

ESM

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 переменные среды нечувствительны к регистру.

ESM

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

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

• <string[]>

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

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

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

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

И process.argv:

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

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

process.execPath

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

• <string>

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

'/usr/local/bin/node'

process.exit([code])

[История]

Версия	Изменения
v20.0.0	Принимает только код типа number или типа string, если он представляет собой целое число.
v0.1.13	Добавлено в: v0.1.13

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

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

Для выхода с кодом 'неудачи':

ESM

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:

ESM

import { exit } from 'node:process'

// Это пример того, чего *не следует* делать:
if (someConditionNotMet()) {
  printUsageToStdout()
  exit(1)
}

CJS

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

// Это пример того, чего *не следует* делать:
if (someConditionNotMet()) {
  printUsageToStdout()
  exit(1)
}

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

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

ESM

import process from 'node:process'

// Как правильно установить код выхода, позволяя
// процессу завершиться корректно.
if (someConditionNotMet()) {
  printUsageToStdout()
  process.exitCode = 1
}

CJS

const process = require('node:process')

// Как правильно установить код выхода, позволяя
// процессу завершиться корректно.
if (someConditionNotMet()) {
  printUsageToStdout()
  process.exitCode = 1
}

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

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

process.exitCode

[История]

Версия	Изменения
v20.0.0	Принимает только код типа number или типа string, если он представляет собой целое число.
v0.11.8	Добавлено в: v0.11.8

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

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

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

process.features.cached_builtins

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

• <булево>

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

process.features.debug

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

• <булево>

Булево значение, равное true, если текущая сборка Node.js является отладочной сборкой.

process.features.inspector

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

• <булево>

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

process.features.ipv6

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

Устарело с: v23.4.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Это свойство всегда истинно, и любые проверки на его основе избыточны.

• <булево>

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

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

process.features.require_module

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

• <boolean>

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

process.features.tls

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

• <boolean>

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

process.features.tls_alpn

Добавлен в: v4.8.0

Устарел с: v23.4.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте process.features.tls вместо этого.

• <boolean>

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

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

process.features.tls_ocsp

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

Устарел с: v23.4.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте process.features.tls вместо этого.

• <boolean>

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

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

process.features.tls_sni

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

Устарел с: v23.4.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Используйте process.features.tls вместо этого.

• <boolean>

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

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

process.features.typescript

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

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1.1 - Активная разработка

• <boolean> | <string>

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

process.features.uv

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

Устарело с: v23.4.0

[Стабильно: 0 - Устарело]

Стабильно: 0 Стабильность: 0 - Устарело. Это свойство всегда истинно, и любые проверки на его основе избыточны.

• <boolean>

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

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

process.finalization.register(ref, callback)

Добавлено в: v22.5.0

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1.1 - Активная разработка

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

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

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

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

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

CJS

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

// Пожалуйста, убедитесь, что функция, переданная в finalization.register(),
// не создает замыкание вокруг ненужных объектов.
function onFinalize(obj, event) {
  // Вы можете сделать все, что хотите с объектом
  obj.dispose()
}

function setup() {
  // Этот объект может быть безопасно собран сборщиком мусора,
  // и результирующая функция завершения не будет вызвана.
  // Нет утечек.
  const myDisposableObject = {
    dispose() {
      // Освободите ваши ресурсы синхронно
    },
  }

  finalization.register(myDisposableObject, onFinalize)
}

setup()

ESM

import { finalization } from 'node:process'

// Пожалуйста, убедитесь, что функция, переданная в finalization.register(),
// не создает замыкание вокруг ненужных объектов.
function onFinalize(obj, event) {
  // Вы можете сделать все, что хотите с объектом
  obj.dispose()
}

function setup() {
  // Этот объект может быть безопасно собран сборщиком мусора,
  // и результирующая функция завершения не будет вызвана.
  // Нет утечек.
  const myDisposableObject = {
    dispose() {
      // Освободите ваши ресурсы синхронно
    },
  }

  finalization.register(myDisposableObject, onFinalize)
}

setup()

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

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

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

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

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

    // Даже что-то подобное крайне не рекомендуется
    // finalization.register(this, () => this.dispose());
  }
  dispose() {}
}

Весьма маловероятно (но не невозможно), что этот объект будет собран сборщиком мусора, но если это не так, dispose будет вызван при вызове process.exit.

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

process.finalization.registerBeforeExit(ref, callback)

Добавлен в: v22.5.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1.1 - Активная разработка

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

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

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

process.finalization.unregister(ref)

Добавлен в: v22.5.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1.1 - Активная разработка

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

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

CJS

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

// Пожалуйста, убедитесь, что функция, переданная в finalization.register(),
// не создает замыкание вокруг ненужных объектов.
function onFinalize(obj, event) {
  // Вы можете сделать все, что хотите с объектом
  obj.dispose()
}

function setup() {
  // Этот объект может быть безопасно собран сборщиком мусора,
  // и результирующая функция завершения работы не будет вызвана.
  // Утечек нет.
  const myDisposableObject = {
    dispose() {
      // Освободите ваши ресурсы синхронно
    },
  }

  finalization.register(myDisposableObject, onFinalize)

  // Сделайте что-нибудь

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

setup()

ESM

import { finalization } from 'node:process'

// Пожалуйста, убедитесь, что функция, переданная в finalization.register(),
// не создает замыкание вокруг ненужных объектов.
function onFinalize(obj, event) {
  // Вы можете сделать все, что хотите с объектом
  obj.dispose()
}

function setup() {
  // Этот объект может быть безопасно собран сборщиком мусора,
  // и результирующая функция завершения работы не будет вызвана.
  // Утечек нет.
  const myDisposableObject = {
    dispose() {
      // Освободите ваши ресурсы синхронно
    },
  }

  // Пожалуйста, убедитесь, что функция, переданная в finalization.register(),
  // не создает замыкание вокруг ненужных объектов.
  function onFinalize(obj, event) {
    // Вы можете сделать все, что хотите с объектом
    obj.dispose()
  }

  finalization.register(myDisposableObject, onFinalize)

  // Сделайте что-нибудь

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

setup()

process.getActiveResourcesInfo()

Добавлено в: v17.3.0, v16.14.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

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

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

ESM

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

console.log('Before:', getActiveResourcesInfo())
setTimeout(() => {}, 1000)
console.log('After:', getActiveResourcesInfo())
// Выведет:
//   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())
// Выведет:
//   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

process.getBuiltinModule(id)

Добавлено в: v22.3.0, v20.16.0

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

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

if (globalThis.process?.getBuiltinModule) {
  // Запуск в Node.js, используется модуль fs Node.js.
  const fs = globalThis.process.getBuiltinModule('fs')
  // Если для загрузки модулей пользователя требуется `require()`, используйте createRequire()
  const module = globalThis.process.getBuiltinModule('module')
  const require = module.createRequire(import.meta.url)
  const foo = require('foo')
}

Если 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()

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

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

ESM

import process from 'node:process'

if (process.getegid) {
  console.log(`Текущий gid: ${process.getegid()}`)
}

CJS

const process = require('node:process')

if (process.getegid) {
  console.log(`Текущий gid: ${process.getegid()}`)
}

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

process.geteuid()

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

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

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

ESM

import process from 'node:process'

if (process.geteuid) {
  console.log(`Текущий uid: ${process.geteuid()}`)
}

CJS

const process = require('node:process')

if (process.geteuid) {
  console.log(`Текущий uid: ${process.geteuid()}`)
}

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

process.getgid()

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

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

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

ESM

import process from 'node:process'

if (process.getgid) {
  console.log(`Текущий gid: ${process.getgid()}`)
}

CJS

const process = require('node:process')

if (process.getgid) {
  console.log(`Текущий gid: ${process.getgid()}`)
}

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

process.getgroups()

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

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

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

ESM

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

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

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

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

ESM

import process from 'node:process'

if (process.getuid) {
  console.log(`Текущий uid: ${process.getuid()}`)
}

CJS

const process = require('node:process')

if (process.getuid) {
  console.log(`Текущий uid: ${process.getuid()}`)
}

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

process.hasUncaughtExceptionCaptureCallback()

Добавлено в: v9.3.0

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

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

process.hrtime([time])

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

[Стабильно: 3 - Устарело]

Стабильно: 3 Стабильность: 3 - Устарело. Используйте process.hrtime.bigint() вместо этого.

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

Это устаревшая версия process.hrtime.bigint(), существовавшая до введения bigint в JavaScript.

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

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

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

ESM

import { hrtime } from 'node:process'

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

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

  console.log(`Тест занял ${diff[0] * NS_PER_SEC + diff[1]} наносекунд`)
  // Тест занял 1000000552 наносекунд
}, 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(`Тест занял ${diff[0] * NS_PER_SEC + diff[1]} наносекунд`)
  // Тест занял 1000000552 наносекунд
}, 1000)

process.hrtime.bigint()

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

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

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

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

ESM

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)

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

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

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

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

ESM

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

console.log(getgroups()) // [ 0 ]
initgroups('nodeuser', 1000) // смена пользователя
console.log(getgroups()) // [ 27, 30, 46, 1000, 0 ]
setgid(1000) // отмена root gid
console.log(getgroups()) // [ 27, 30, 46, 1000 ]

CJS

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

console.log(getgroups()) // [ 0 ]
initgroups('nodeuser', 1000) // смена пользователя
console.log(getgroups()) // [ 27, 30, 46, 1000, 0 ]
setgid(1000) // отмена root gid
console.log(getgroups()) // [ 27, 30, 46, 1000 ]

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

process.kill(pid[, signal])

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

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

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

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

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

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

ESM

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

process.on('SIGHUP', () => {
  console.log('Получен сигнал SIGHUP.')
})

setTimeout(() => {
  console.log('Выход.')
  process.exit(0)
}, 100)

kill(process.pid, 'SIGHUP')

CJS

const process = require('node:process')

process.on('SIGHUP', () => {
  console.log('Получен сигнал SIGHUP.')
})

setTimeout(() => {
  console.log('Выход.')
  process.exit(0)
}, 100)

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

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

process.loadEnvFile(path)

Добавлено в: v21.7.0, v20.12.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1.1 - Активная разработка

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

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

CJS

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

ESM

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

process.mainModule

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

Устарело с: v14.0.0

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте require.main вместо этого.

• <Object>

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

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

process.memoryUsage()

[История]

Версия	Изменения
v13.9.0, v12.17.0	Добавлен arrayBuffers в возвращаемый объект.
v7.2.0	Добавлен external в возвращаемый объект.
v0.1.16	Добавлено в: v0.1.16

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

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

ESM

import { memoryUsage } from 'node:process'

console.log(memoryUsage())
// Выводит:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }

CJS

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

console.log(memoryUsage())
// Выводит:
// {
//  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()

Добавлено в: v15.6.0, v14.18.0

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

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

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

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

ESM

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

[История]

Версия	Изменения
v22.7.0, v20.18.0	Стабильность изменена на Legacy.
v18.0.0	Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v1.8.1	Теперь поддерживаются дополнительные аргументы после callback.
v0.1.26	Добавлено в: v0.1.26

[Стабильность: 3 - Legacy]

Стабильность: 3 Стабильность: 3 - Legacy: Используйте queueMicrotask() вместо этого.

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

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

ESM

import { nextTick } from 'node:process'

console.log('start')
nextTick(() => {
  console.log('nextTick callback')
})
console.log('scheduled')
// Вывод:
// start
// scheduled
// nextTick callback

CJS

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

console.log('start')
nextTick(() => {
  console.log('nextTick callback')
})
console.log('scheduled')
// Вывод:
// start
// scheduled
// nextTick callback

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

ESM

import { nextTick } from 'node:process'

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

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

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

// thing.startDoingStuff() вызывается сейчас, а не раньше.

CJS

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

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

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

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

// thing.startDoingStuff() вызывается сейчас, а не раньше.

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

// ПРЕДУПРЕЖДЕНИЕ! НЕ ИСПОЛЬЗОВАТЬ! ОПАСНОСТЬ!
function maybeSync(arg, cb) {
  if (arg) {
    cb()
    return
  }

  fs.stat('file', cb)
}

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

const maybeTrue = Math.random() > 0.5

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

bar()

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

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

ESM

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 каждый раз, когда очередь "next tick" очищается, очередь микрозадач очищается сразу после неё.

ESM

import { nextTick } from 'node:process'

Promise.resolve().then(() => console.log(2))
queueMicrotask(() => console.log(3))
nextTick(() => console.log(1))
// Вывод:
// 1
// 2
// 3

CJS

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

Promise.resolve().then(() => console.log(2))
queueMicrotask(() => console.log(3))
nextTick(() => console.log(1))
// Вывод:
// 1
// 2
// 3

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

console.log('start')
queueMicrotask(() => {
  console.log('microtask callback')
})
console.log('scheduled')
// Вывод:
// start
// scheduled
// microtask callback

Следует отметить одно различие между двумя 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')
// Вывод:
// start
// scheduled
// microtask 3

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

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

process.noDeprecation

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

• <boolean>

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

process.permission

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

• <Object>

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

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

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

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

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

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

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

Доступные scope:

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

// Проверка, есть ли у процесса разрешение на чтение файла README
process.permission.has('fs.read', './README.md')
// Проверка, есть ли у процесса разрешения на операции чтения
process.permission.has('fs.read')

process.pid

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

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

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

ESM

import { pid } from 'node:process'

console.log(`PID этого процесса: ${pid}`)

CJS

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

console.log(`PID этого процесса: ${pid}`)

process.platform

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

• <строка>

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

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

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

ESM

import { platform } from 'node:process'

console.log(`Эта платформа: ${platform}`)

CJS

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

console.log(`Эта платформа: ${platform}`)

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

process.ppid

Добавлен в: v9.2.0, v8.10.0, v6.13.0

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

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

ESM

import { ppid } from 'node:process'

console.log(`PID родительского процесса: ${ppid}`)

CJS

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

console.log(`PID родительского процесса: ${ppid}`)

process.release

[История]

Версия	Изменения
v4.2.0	Теперь поддерживается свойство lts.
v3.0.0	Добавлено в: v3.0.0

• <Объект>

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

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

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

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

process.report

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.8.0	Добавлено в: v11.8.0

• <Объект>

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

process.report.compact

Добавлен в: v13.12.0, v12.17.0

• <булево>

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

ESM

import { report } from 'node:process'

console.log(`Отчеты в компактном формате? ${report.compact}`)

CJS

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

console.log(`Отчеты в компактном формате? ${report.compact}`)

process.report.directory

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.12.0	Добавлено в: v11.12.0

• <строка>

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

ESM

import { report } from 'node:process'

console.log(`Каталог отчета: ${report.directory}`)

CJS

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

console.log(`Каталог отчета: ${report.directory}`)

process.report.filename

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.12.0	Добавлено в: v11.12.0

• <строка>

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

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

ESM

import { report } from 'node:process'

console.log(`Имя файла отчета: ${report.filename}`)

CJS

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

console.log(`Имя файла отчета: ${report.filename}`)

process.report.getReport([err])

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.8.0	Добавлено в: v11.8.0

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

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

ESM

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

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

// Аналогично 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)

// Аналогично process.report.writeReport()
const fs = require('node:fs')
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8')

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

process.report.reportOnFatalError

[История]

Версия	Изменения
v15.0.0, v14.17.0	Этот API больше не является экспериментальным.
v11.12.0	Добавлено в: v11.12.0

• <boolean>

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

ESM

import { report } from 'node:process'

console.log(`Отчет о фатальной ошибке: ${report.reportOnFatalError}`)

CJS

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

console.log(`Отчет о фатальной ошибке: ${report.reportOnFatalError}`)

process.report.reportOnSignal

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.12.0	Добавлено в: v11.12.0

• <boolean>

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

ESM

import { report } from 'node:process'

console.log(`Отчет о сигнале: ${report.reportOnSignal}`)

CJS

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

console.log(`Отчет о сигнале: ${report.reportOnSignal}`)

process.report.reportOnUncaughtException

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.12.0	Добавлено в: v11.12.0

• <boolean>

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

ESM

import { report } from 'node:process'

console.log(`Отчет об исключении: ${report.reportOnUncaughtException}`)

CJS

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

console.log(`Отчет об исключении: ${report.reportOnUncaughtException}`)

process.report.excludeEnv

Добавлено в: v23.3.0

• <boolean>

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

process.report.signal

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.12.0	Добавлено в: v11.12.0

• <string>

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

ESM

import { report } from 'node:process'

console.log(`Сигнал отчета: ${report.signal}`)

CJS

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

console.log(`Сигнал отчета: ${report.signal}`)

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

[История]

Версия	Изменения
v13.12.0, v12.17.0	Этот API больше не является экспериментальным.
v11.8.0	Добавлено в: v11.8.0

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

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

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

ESM

import { report } from 'node:process'

report.writeReport()

CJS

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

report.writeReport()

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

process.resourceUsage()

Добавлено в: v12.6.0

• Возвращает: <Объект> использование ресурсов для текущего процесса. Все эти значения берутся из вызова 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.

ESM

import { resourceUsage } from 'node:process'

console.log(resourceUsage())
/*
  Выведет:
  {
    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())
/*
  Выведет:
  {
    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])

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

• message <Object>

• sendHandle <net.Server> | <net.Socket>

• options <Object> используется для параметризации отправки определённых типов дескрипторов. options поддерживает следующие свойства:

  • keepOpen <boolean> Значение, которое можно использовать при передаче экземпляров net.Socket. При значении true сокет остаётся открытым в отправляющем процессе. По умолчанию: false.

• callback <Function>

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

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

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

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

process.setegid(id)

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

• id <string> | <number> Имя или ID группы

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

ESM

import process from 'node:process'

if (process.getegid && process.setegid) {
  console.log(`Текущий gid: ${process.getegid()}`)
  try {
    process.setegid(501)
    console.log(`Новый gid: ${process.getegid()}`)
  } catch (err) {
    console.error(`Не удалось установить gid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getegid && process.setegid) {
  console.log(`Текущий gid: ${process.getegid()}`)
  try {
    process.setegid(501)
    console.log(`Новый gid: ${process.getegid()}`)
  } catch (err) {
    console.error(`Не удалось установить gid: ${err}`)
  }
}

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

process.seteuid(id)

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

• id <string> | <number> Имя пользователя или ID

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

ESM

import process from 'node:process'

if (process.geteuid && process.seteuid) {
  console.log(`Текущий uid: ${process.geteuid()}`)
  try {
    process.seteuid(501)
    console.log(`Новый uid: ${process.geteuid()}`)
  } catch (err) {
    console.error(`Не удалось установить uid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.geteuid && process.seteuid) {
  console.log(`Текущий uid: ${process.geteuid()}`)
  try {
    process.seteuid(501)
    console.log(`Новый uid: ${process.geteuid()}`)
  } catch (err) {
    console.error(`Не удалось установить uid: ${err}`)
  }
}

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

process.setgid(id)

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

• id <string> | <number> Имя группы или ID

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

ESM

import process from 'node:process'

if (process.getgid && process.setgid) {
  console.log(`Текущий gid: ${process.getgid()}`)
  try {
    process.setgid(501)
    console.log(`Новый gid: ${process.getgid()}`)
  } catch (err) {
    console.error(`Не удалось установить gid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getgid && process.setgid) {
  console.log(`Текущий gid: ${process.getgid()}`)
  try {
    process.setgid(501)
    console.log(`Новый gid: ${process.getgid()}`)
  } catch (err) {
    console.error(`Не удалось установить gid: ${err}`)
  }
}

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

process.setgroups(groups)

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

• groups <integer[]>

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

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

ESM

import process from 'node:process'

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501])
    console.log(process.getgroups()) // новые группы
  } catch (err) {
    console.error(`Не удалось установить группы: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501])
    console.log(process.getgroups()) // новые группы
  } catch (err) {
    console.error(`Не удалось установить группы: ${err}`)
  }
}

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

process.setuid(id)

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

• id <integer> | <string>

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

ESM

import process from 'node:process'

if (process.getuid && process.setuid) {
  console.log(`Текущий uid: ${process.getuid()}`)
  try {
    process.setuid(501)
    console.log(`Новый uid: ${process.getuid()}`)
  } catch (err) {
    console.error(`Не удалось установить uid: ${err}`)
  }
}

CJS

const process = require('node:process')

if (process.getuid && process.setuid) {
  console.log(`Текущий uid: ${process.getuid()}`)
  try {
    process.setuid(501)
    console.log(`Новый uid: ${process.getuid()}`)
  } catch (err) {
    console.error(`Не удалось установить uid: ${err}`)
  }
}

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

process.setSourceMapsEnabled(val)

Добавлено в: v16.6.0, v14.18.0

[Стабильность: 1 — Экспериментально]

Стабильность: 1 Стабильность: 1 — Экспериментально

• val <boolean>

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

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

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

process.setUncaughtExceptionCaptureCallback(fn)

Добавлено в: v9.3.0

• fn <Function> | <null>

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

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

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

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

process.sourceMapsEnabled

Добавлено в: v20.7.0, v18.19.0

[Стабильность: 1 — Экспериментально]

Стабильность: 1 Стабильность: 1 — Экспериментально

• <boolean>

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

process.stderr

• <Поток>

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

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

process.stderr.fd

• <число>

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

process.stdin

• <Поток>

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

Для получения подробной информации о чтении из stdin см. readable.read().

Как поток Duplex, process.stdin также может использоваться в "старом" режиме, совместимом со скриптами, написанными для Node.js до версии 0.10. Для получения дополнительной информации см. Совместимость потоков.

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

process.stdin.fd

• <число>

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

process.stdout

• <Поток>

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

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

ESM

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:

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

Синхронная запись позволяет избежать таких проблем, как неожиданное переплетение вывода, записанного с помощью 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

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

process.throwDeprecation

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

• <boolean>

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

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

process.title

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

• <string>

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

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

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

process.traceDeprecation

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

• <boolean>

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

process.umask()

[История]

Версия	Изменения
v14.0.0, v12.19.0	Вызов process.umask() без аргументов устарел.
v0.1.19	Добавлено в: v0.1.19

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело. Вызов process.umask() без аргументов приводит к двукратному изменению маски umask для всего процесса. Это создаёт условие гонки между потоками и является потенциальной уязвимостью безопасности. Безопасного кроссплатформенного альтернативного API нет.

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

process.umask(mask)

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

• mask <string> | <integer>

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

ESM

import { umask } from 'node:process'

const newmask = 0o022
const oldmask = umask(newmask)
console.log(`Изменена umask с ${oldmask.toString(8)} на ${newmask.toString(8)}`)

CJS

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

const newmask = 0o022
const oldmask = umask(newmask)
console.log(`Изменена umask с ${oldmask.toString(8)} на ${newmask.toString(8)}`)

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

process.uptime()

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

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

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

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

process.version

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

• <string>

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

ESM

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

[История]

Версия	Изменения
v9.0.0	Свойство v8 теперь включает в себя специфичный для Node.js суффикс.
v4.2.0	Теперь поддерживается свойство icu.
v0.2.0	Добавлено в: v0.2.0

• <Object>

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

ESM

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',
  sqlite: '3.46.0',
  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' }

Коды выхода

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

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