Node.js v14.16.1 文档


目录

process(进程)#

中英对照

源代码: lib/process.js

process 对象是一个全局变量,提供了有关当前 Node.js 进程的信息并对其进行控制。 作为全局变量,它始终可供 Node.js 应用程序使用,无需使用 require()。 它也可以使用 require() 显式地访问:

const process = require('process');

进程事件#

中英对照

process 对象是 EventEmitter 的实例。

'beforeExit' 事件#

中英对照

当 Node.js 清空其事件循环并且没有其他工作要调度时,则 'beforeExit' 事件会被触发。 通常,当没有工作被调度时,则 Node.js 进程会退出,但是在 'beforeExit' 事件上注册的监听器可以进行异步的调用,从而使 Node.js 进程继续。

监听器回调函数被调用时会传入 process.exitCode 的值作为唯一的参数。

对于导致显式终止的情况(例如调用 process.exit() 或未捕获的异常),则不会触发 'beforeExit' 事件。

除非打算调度额外的工作,否则不应该使用 'beforeExit' 代替 'exit' 事件。

process.on('beforeExit', (code) => {
  console.log('进程 beforeExit 事件的退出码: ', code);
});

process.on('exit', (code) => {
  console.log('进程 exit 事件的退出码: ', code);
});

console.log('此消息会最先显示');

// 打印:
// 此消息会最先显示
// 进程 beforeExit 事件的退出码: 0
// 进程 exit 事件的退出码: 0

'disconnect' 事件#

中英对照

如果使用 IPC 通道衍生 Node.js 进程(参见子进程集群文档),则在 IPC 通道关闭时将触发 'disconnect' 事件。

'exit' 事件#

中英对照

当 Node.js 进程因以下原因之一即将退出时,则会触发 'exit' 事件:

  • process.exit() 方法被显式地调用;
  • Node.js 事件循环不再需要执行任何其他的工作。

此时无法阻止事件循环的退出,并且一旦所有的 'exit' 事件的监听器都已完成运行,则 Node.js 进程就会终止。

监听器回调函数被调用时会传入退出码(由 process.exitCode 属性指定,或是传给 process.exit() 方法的 exitCode 参数)。

process.on('exit', (code) => {
  console.log(`即将退出,退出码: ${code}`);
});

监听器函数必须只执行同步的操作。 在调用 'exit' 事件监听器之后,Node.js 进程会立即退出,从而使仍在事件循环中排队的任何其他的工作都被放弃。 例如,在以下示例中,定时器中的操作不会发生:

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('此处不会运行');
  }, 0);
});

'message' 事件#

中英对照

如果使用 IPC 通道衍生 Node.js 进程(参见子进程集群文档),则只要子进程收到父进程使用 childprocess.send() 发送的消息,就会触发 'message' 事件。

消息会进行序列化和解析。 生成的消息可能与最初发送的消息不同。

如果在衍生进程时使用了 serialization 选项设置为 'advanced',则 message 参数可以包含 JSON 无法表示的数据。 有关更多详细信息,请参见 child_process 的高级序列化

'multipleResolves' 事件#

中英对照

  • type <string> 错误类型。'resolve''reject' 之一。
  • promise <Promise> 不止一次'resolve''reject'的 Promise。
  • value <any> 在原始解析后'resolve''reject'的 Promise 的值。

只要 Promise 有以下情况,就会触发 'multipleResolves' 事件:

  • resolve不止一次。
  • reject不止一次。
  • resolve后reject。
  • reject后resolve。

这对于在使用 Promise 构造函数时跟踪应用程序中的潜在错误非常有用,因为会以静默方式吞没多个解决。 但是,此事件的发生并不一定表示错误。 例如,Promise.race() 可以触发 'multipleResolves' 事件。

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('第一次调用');
      resolve('吞没解决');
      reject(new Error('吞没解决'));
    });
  } catch {
    throw new Error('失败');
  }
}

main().then(console.log);
// resolve: Promise { '第一次调用' } '吞没解决'
// reject: Promise { '第一次调用' } Error: 吞没解决
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// 第一次调用

'rejectionHandled' 事件#

中英对照

  • promise <Promise> 最近处理的 Promise。

每当 Promise 被拒绝并且错误句柄附加到它(例如,使用 promise.catch())晚于一个 Node.js 事件循环时,就会触发 'rejectionHandled' 事件。

Promise 对象之前已经在 'unhandledRejection' 事件中触发,但在处理过程中获得了拒绝句柄。

Promise 链中没有顶层的概念,总是可以处理拒绝。 本质上自身是异步的,可以在未来的某个时间点处理 Promise 拒绝,可能比触发 'unhandledRejection' 事件所需的事件循环更晚。

另一种表述的方式就是,与同步代码中不断增长的未处理异常列表不同,使用 Promise 可能会有一个不断增长和缩小的未处理拒绝列表。

在同步代码中,当未处理的异常列表增长时,会触发 'uncaughtException' 事件。

在异步代码中,当未处理的拒绝列表增长时会触发 'unhandledRejection' 事件,并且当未处理的拒绝列表缩小时会触发 'rejectionHandled' 事件。

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

在这个例子中, unhandledRejectionsMap 将随着时间的推移而增长和缩小,反映出拒绝开始未处理然后被处理。 可以定期地(这对可能长时间运行的应用程序最好)或进程退出时(这对脚本来说可能是最方便的)在错误日志中记录此类错误。

'uncaughtException' 事件#

中英对照

  • err <Error> 未捕获的异常。
  • origin <string> 表明异常的来源(来自未处理的拒绝、或来自同步的错误)。 可以是 'uncaughtException''unhandledRejection'。 后者仅用于 --unhandled-rejections 标志被设置为 strictthrow 且有未处理的拒绝。

当未捕获的 JavaScript 异常冒泡回到事件循环时,则会触发 'uncaughtException' 事件。 默认情况下,Node.js 会这样处理此类异常:打印堆栈跟踪到 stderr 并使用退出码 1 来退出,且会覆盖任何先前设置的 process.exitCode。 为 'uncaughtException' 事件添加句柄会覆盖此默认行为。 另外,如果在 'uncaughtException' 句柄中更改 process.exitCode,则会使进程以提供的退出码退出。 否则,在存在这样的句柄的情况下,进程会以退出码 0 退出。

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `捕获的异常: ${err}\n` +
    `异常的来源: ${origin}`
  );
});

setTimeout(() => {
  console.log('这里仍然会运行');
}, 500);

// 故意引起异常,但不要捕获它。
nonexistentFunc();
console.log('这里不会运行');

通过添加 'uncaughtExceptionMonitor' 事件监听器,可以监视 'uncaughtException' 事件但不覆盖默认的退出进程的行为。

注意: 正确地使用 uncaughtException#

中英对照

'uncaughtException' 事件是一种粗糙的异常处理的机制,只能用作不得已的最后手段。 此事件不应该被用作相当于就算出错也继续执行。 未处理的异常本身就意味着应用程序处于未定义的状态。 尝试恢复应用程序代码而未正确地从异常中恢复,可能会导致其他无法预料和不可预测的问题。

此事件的句柄中抛出的异常不会被捕获。 进程会以非零的退出码退出,并打印堆栈跟踪。 这是为了避免无限的循环。

在出现未捕获的异常时尝试去恢复,就类似于在升级电脑时拔掉电源线。 10次中有9次不会出现问题。 但是第10次时系统就可能出现崩溃。

'uncaughtException' 事件的正确使用方式是:在进程被关闭之前,执行清理已分配资源(比如文件描述符、句柄等)的同步操作。 在 'uncaughtException' 事件触发之后,尝试恢复正常运行是不安全的。

重启已经崩溃的应用是更可靠的方式,不管 uncaughtException 事件是否被触发,应该在独立的过程中使用外部监视器,以检测应用程序故障并根据需要恢复或重启。

'uncaughtExceptionMonitor' 事件#

  • err <Error> The uncaught exception.
  • origin <string> Indicates if the exception originates from an unhandled rejection or from synchronous errors. Can either be 'uncaughtException' or 'unhandledRejection'. The latter is only used in conjunction with the --unhandled-rejections flag set to strict or throw and an unhandled rejection.

The 'uncaughtExceptionMonitor' event is emitted before an 'uncaughtException' event is emitted or a hook installed via process.setUncaughtExceptionCaptureCallback() is called.

Installing an 'uncaughtExceptionMonitor' listener does not change the behavior once an 'uncaughtException' event is emitted. The process will still crash if no 'uncaughtException' listener is installed.

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

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.js

'unhandledRejection' 事件#

中英对照

Promise 被拒绝且在事件循环的此次轮询中没有绑定错误句柄时,则会触发 'unhandledRejection 事件。 当使用 Promise 进行编程时,异常会被封装为“被拒绝的 promise”。 拒绝可以被 promise.catch() 捕获并处理,并且在 Promise 链中传播。 'unhandledRejection 事件在检测和跟踪被拒绝的(且拒绝还未被处理)promise 时很有用。

process.on('unhandledRejection', (reason, promise) => {
  console.log('未处理的拒绝:', promise, '原因:', reason);
  // 记录日志、抛出错误、或其他逻辑。
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // 故意输错 (`pasre`)。
}); // 没有 `.catch()` 或 `.then()`。

以下代码也会触发 'unhandledRejection' 事件:

function SomeResource() {
  // 设置 loaded 的状态为被拒绝的 promise。
  this.loaded = Promise.reject(new Error('错误信息'));
}

const resource = new SomeResource();
// resource.loaded 上没有 .catch 或 .then。

在此示例中,可以像其他 'unhandledRejection' 事件一样,将拒绝作为开发者错误进行跟踪。 为了解决此类故障,可以在 resource.loaded 上绑定一个无操作的 .catch(() => { }) 句柄,这样就可以阻止 'unhandledRejection' 事件的触发。

'warning' 事件#

中英对照

  • warning <Error> 警告的主要属性有:
    • name <string> 警告的名称。默认值: 'Warning'
    • message <string> 系统提供的对此警告的描述。
    • stack <string> 当警告触发时,包含代码位置的堆栈信息。

任何时候 Node.js 触发进程警告,都会触发 'warning' 事件。

进程警告与进程错误的相似之处,在于两者都描述了需要引起用户注意的异常条件。 区别在于,警告不是 Node.js 和 Javascript 错误处理流程的正式组成部分。 一旦探测到可能导致应用性能问题,缺陷或安全隐患相关的代码实践,Node.js 就可发出警告。

process.on('warning', (warning) => {
  console.warn(warning.name);    // 打印警告名称
  console.warn(warning.message); // 打印警告信息
  console.warn(warning.stack);   // 打印堆栈信息
});

默认Node.js会打印进程警告到stderr。使用--no-warnings的命令行选项可以阻止默认从console输出信息, 但是'warning'事件仍然会被process对象发出。

下面的例子展示了当一个事件绑定了太多的监听器时,输出到stderr的警告。

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

与上述相反,如下例子关闭了默认的警告输出,并且给'warning'事件添加了一个定制的处理器。

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

--trace-warnings命令行选项可以让默认的控制台输出警告信息时,包含警告的全部堆栈信息。

使用--throw-deprecation命令行选项标志启动Node.js,会使得自定义的弃用警告作为异常信息抛出来。

使用--trace-deprecation命令行选项标志,会使得自定义的弃用警告打印到stderr,包括其堆栈信息。

使用--no-deprecation命令行选项标志,会阻止报告所有的自定义的弃用警告。

*-deprecation 命令行选项标志,只会影响使用名字为 'DeprecationWarning' 的警告。

触发自定义的告警#

中英对照

查看process.emitWarning()的描述,其中包含关于触发定制警告或特定应用警告的信息。

信号事件#

中英对照

当 Node.js 进程接收到信号时,则会触发信号事件。 signal(7) 文档可查看标准 POSIX 的信号名称的列表,例如 'SIGINT''SIGHUP' 等。

信号在 Worker 线程上不可用。

信号句柄会接收信号的名称('SIGINT''SIGTERM' 等)作为第一个参数。

每个事件的名称是信号的通用名称的大写 (比如 'SIGINT' 事件对应 SIGINT 信号)。

// 开始从 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)。 可以给其绑定监听器,但是 Windows 上 Node.js 会在触发后 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() 的模拟:

  • 发送 SIGINTSIGTERMSIGKILL 会使目标进程被无条件地终止,然后子进程会报告该进程已被信号终止。
  • 发送信号 0 可以用作与平台无关的方式来测试进程的存在性。

process.abort()#

中英对照

process.abort() 方法会使 Node.js 进程立即结束,并生成一个核心文件。

Worker 线程中没有此特性。

process.allowedNodeEnvironmentFlags#

中英对照

process.allowedNodeEnvironmentFlags 属性是 NODE_OPTIONS 环境变量中允许的特殊只读标志的 Set

process.allowedNodeEnvironmentFlags 扩展了 Set,但重写了 Set.prototype.has 以识别几种不同的可能标志的表示。 在以下情况下, process.allowedNodeEnvironmentFlags.has() 将会返回 true

  • 标志可以省略前导单(-)或双(--)破折号。例如, inspect-brk 用于 --inspect-brk,或 r 用于 -r
  • 传给 V8 的标志(如 --v8-options 中所列)可以替换下划线的一个或多个非前导短划线,反之亦然。例如, --perf_basic_prof--perf-basic-prof--perf_basic-prof 等。
  • 标志可以包含一个或多个等号(=)字符。包含第一个等号后的所有字符都将被忽略。例如, --stack-trace-limit=100
  • NODE_OPTIONS 中必须允许标志。

当迭代 process.allowedNodeEnvironmentFlags 时,标志只出现一次。 每个都将会以一个或多个破折号开头。 传给 V8 的标志将包含下划线而不是非前导破折号:

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

process.allowedNodeEnvironmentFlagsadd()clear()delete() 方法不执行任何操作,并且将会以静默方式失败。

如果在没有 NODE_OPTIONS 支持的情况下编译 Node.js(在 process.config 中显示),则 process.allowedNodeEnvironmentFlags 将会包含允许的内容。

process.arch#

中英对照

编译 Node.js 二进制文件的操作系统的 CPU 架构。 可能的值有:'arm''arm64''ia32''mips''mipsel''ppc''ppc64''s390''s390x''x32''x64'

console.log(`该处理器的架构是 ${process.arch}`);

process.argv#

中英对照

process.argv 属性会返回一个数组,其中包含当 Node.js 进程被启动时传入的命令行参数。 第一个元素是 process.execPath。 如果需要访问 argv[0] 的原始值,则参见 process.argv0。 第二个元素是正被执行的 JavaScript 文件的路径。 其余的元素是任何额外的命令行参数。

例如,假设 process-args.js 的脚本如下:

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

启动 Node.js 进程:

$ node process-args.js 参数1 参数2 参数3

输出如下:

0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: 参数1
3: 参数2
4: 参数3

process.argv0#

中英对照

process.argv0 属性保存当 Node.js 启动时传入的 argv[0] 的原始值的只读副本。

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

process.channel#

中英对照

如果 Node.js 进程是由 IPC 通道(参见子进程文档)方式创建的, process.channel 属性保存 IPC 通道的引用。 如果 IPC 通道不存在,则此属性值为 undefined

process.channel.ref()#

This method makes the IPC channel keep the event loop of the process running if .unref() has been called before.

Typically, this is managed through the number of 'disconnect' and 'message' listeners on the process object. However, this method can be used to explicitly request a specific behavior.

process.channel.unref()#

This method makes the IPC channel not keep the event loop of the process running, and lets it finish even while the channel is open.

Typically, this is managed through the number of 'disconnect' and 'message' listeners on the process object. However, this method can be used to explicitly request a specific behavior.

process.chdir(directory)#

中英对照

process.chdir() 方法可以变更 Node.js 进程的当前工作目录,如果操作失败(例如,指定的 directory 不存在)则抛出异常。

console.log(`起始的目录: ${process.cwd()}`);
try {
  process.chdir('/tmp');
  console.log(`新的目录: ${process.cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

此特性在 Worker 线程中不可用。

process.config#

中英对照

process.config 属性返回一个 Object,其中包含用于编译当前 Node.js 可执行文件的配置选项的 JavaScript 表示形式。 这与运行 ./configure 脚本时生成的 config.gypi 文件相同。

可能的输出样例:

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

process.config 属性值不是只读的,在 Node.js 生态系统中已经有模块扩展、修改或完全替换了 process.config 的值。

process.connected#

中英对照

如果 Node.js 进程是由 IPC 通道(参见子进程集群的文档)的方式创建,则只要 IPC 通道保持连接, process.connected 属性就会返回 trueprocess.disconnect() 被调用后,此属性会返回 false

一旦 process.connectedfalse,则不能通过 IPC 通道使用 process.send() 发送信息。

process.cpuUsage([previousValue])#

中英对照

process.cpuUsage() 方法返回包含当前进程的用户 CPU 时间和系统 CPU 时间的对象。 此对象包含 usersystem 属性,属性值的单位都是微秒(百万分之一秒)。 用户和系统的属性值分别计算了执行用户程序和系统程序的时间,如果此进程在执行任务时是基于多核 CPU,值可能比实际花费的时间要大。

上一次调用 process.cpuUsage() 方法的结果,可以作为参数值传递给此方法,得到的结果是与上一次的差值。

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

// 将 CPU 旋转 500 毫秒。
const now = Date.now();
while (Date.now() - now < 500);

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

process.cwd()#

中英对照

process.cwd() 方法会返回 Node.js 进程的当前工作目录。

console.log(`当前工作目录是: ${process.cwd()}`);

process.debugPort#

中英对照

Node.js 调试器使用的端口。

process.debugPort = 5858;

process.disconnect()#

中英对照

如果 Node.js 进程是从 IPC 通道衍生出来的(参见子进程集群的文档),则 process.disconnect() 函数会关闭到父进程的 IPC 通道,以允许子进程一旦没有其他链接来保持活跃就优雅地关闭。

调用 process.disconnect() 的效果和父进程调用 ChildProcess.disconnect() 的一样。

如果 Node.js 进程不是从 IPC 通道衍生出来的,则调用 process.disconnect() 将会返回 undefined

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

中英对照

process.dlopen() 方法允许动态地加载共享对象。 它主要由 require() 用于加载 C++ 插件,除特殊情况外,不应直接使用。 换句话说,除非有特殊原因(例如自定义的 dlopen 标志或从 ES 模块加载),否则 require() 应优先于 process.dlopen()

flags 参数是一个允许指定 dlopen 行为的整数。 有关详细信息,请参见 os.constants.dlopen 文档。

调用 process.dlopen() 时的一个重要的要求是必须传入 module 实例。 可以通过 module.exports 访问 C++ 插件导出的函数。

下面的示例显示了如何加载导出 foo 函数的名为 local.node 的 C++ 插件。 通过传入 RTLD_NOW 常量,将在调用返回之前加载所有符号。 在此示例中,假定常量可用。

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

process.emitWarning(warning[, options])#

中英对照

  • 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' 事件增加句柄来监听这些警告。

// 使用代码和其他详细信息触发警告。
process.emitWarning('出错啦', {
  code: 'MY_WARNING',
  detail: '一些额外的信息'
});
// 触发:
// (node:56338) [MY_WARNING] Warning: 出错啦
// 一些额外的信息

在上面例子中, process.emitWarning() 内部生成了一个 Error 对象,并传给 'warning' 句柄。

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // '出错啦'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // '一些额外的信息'
});

如果 warning 是一个 Error 对象,则 options 参数会被忽略。

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

中英对照

  • warning <string> | <Error> 触发的警告。
  • type <string>warning 是一个 String 时,则 type 是用于被触发的警告类型的名称。 默认值: 'Warning'
  • code <string> 要触发的警告实例的唯一标识符。
  • ctor <Function>warning 是一个 String 时,则 ctor 是一个可选的函数,用于限制生成的堆栈信息。默认值: process.emitWarning

process.emitWarning() 方法可用于触发自定义或应用特定的进程警告。 可以通过给 'warning' 事件增加句柄来监听这些警告。

// 使用字符串触发警告。
process.emitWarning('出错啦');
// 触发: (node: 56338) Warning: 出错啦
// 使用字符串和类型触发警告。
process.emitWarning('出错啦', 'CustomWarning');
// 触发: (node:56338) CustomWarning: 出错啦
process.emitWarning('出错啦', 'CustomWarning', 'WARN001');
// 触发: (node:56338) [WARN001] CustomWarning: 出错啦

在前面的每个示例中, process.emitWarning() 内部生成了一个 Error 对象,并传给 'warning' 句柄。

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

如果 warning 是一个 Error 对象,则它将会被透传给 'warning' 事件句柄(并且将会忽略可选的 typecodector 参数):

// 使用错误对象触发警告。
const myWarning = new Error('出错啦');
// 使用错误名称属性指定类型名称。
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

process.emitWarning(myWarning);
// 触发: (node:56338) [WARN001] CustomWarning: 出错啦

如果 warning 不是一个字符串或 Error,则会抛出 TypeError

当进程警告使用 Error 对象时,进程警告机制并不是常用的错误处理机制的替代方式。

如果警告的 type'DeprecationWarning',则会涉及如下额外的处理:

  • 如果使用 --throw-deprecation 命令行标识,则弃用的警告会作为异常抛出,而不是作为事件被触发。
  • 如果使用--no-deprecation 命令行标识,则弃用的警告会被忽略。
  • 如果使用--trace-deprecation 命令行标识,则弃用的警告及其全部堆栈信息会被打印到 stderr

避免重复告警#

中英对照

作为最佳实践,警告应该在每个进程中最多发出一次。 为了达到上述的要求,推荐在使用emitWarning()之前用一个简单的布尔值做判断,如下例所示:

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    process.emitWarning('只警告一次');
  }
}
emitMyWarning();
// 触发: (node: 56339) Warning: 只警告一次
emitMyWarning();
// 什么都没触发。

process.env#

中英对照

process.env 属性会返回包含用户环境的对象。 参见 environ(7)

此对象的示例如下所示:

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

可以修改此对象,但这些修改不会反映到 Node.js 进程之外,或者(除非明确地要求)反映到其他 Worker 线程。 换句话说,以下示例不会起作用:

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

以下示例则会起作用:

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

process.env 上为属性赋值会隐式地将值转换为字符串。 不推荐使用此行为。 当值不是字符串、数字或布尔值时,Node.js 未来的版本可能会抛出错误。

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

使用 delete 可以从 process.env 中删除属性。

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

在 Windows 操作系统上,环境变量不区分大小写。

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

除非在创建 Worker 实例时显式地指定,否则每个 Worker 线程都有自己的 process.env 副本(基于其父线程的 process.env,或者指定为 Worker 构造函数的 env 选项的任何内容)。 对于 process.env 的更改在 Worker 线程中是不可见的,并且只有主线程可以做出对操作系统或原生插件可见的更改。

process.execArgv#

中英对照

process.execArgv 属性返回当 Node.js 进程被启动时,Node.js 特定的命令行选项。 这些选项在 process.argv 属性返回的数组中不会出现,并且这些选项中不会包括 Node.js 的可执行脚本名称或者任何在脚本名称后面出现的选项。 这些选项在创建子进程时是有用的,因为他们包含了与父进程一样的执行环境信息。

$ node --harmony script.js --version

process.execArgv 的结果:

['--harmony']

process.argv 的结果:

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

关于具有此属性的工作线程的详细行为,详见 Worker 构造函数

process.execPath#

中英对照

process.execPath 属性会返回启动 Node.js 进程的可执行文件的绝对路径。 符号链接(如果有)会被处理。

'/usr/local/bin/node'

process.exit([code])#

中英对照

process.exit() 方法以退出状态 code 指示 Node.js 同步地终止进程。 如果省略 code,则使用成功代码 0process.exitCode 的值(如果已设置)退出。 在所有的 'exit' 事件监听器被调用之前,Node.js 不会终止。

使用失败代码退出:

process.exit(1);

执行 Node.js 的 shell 可以看到退出码为 1

调用 process.exit() 会强制进程尽快退出,即使还有尚未完全完成的异步操作在等待,包括对 process.stdoutprocess.stderr 的 I/O 操作。

在大多数情况下,实际上不需要显式地调用 process.exit()。 如果事件循环中没有待处理的额外工作,则 Node.js 进程会自行退出。 process.exitCode 属性可以设置来告诉进程使用什么退出码(当进程正常退出时)。

例如,以下示例描述了 process.exit() 方法的错误用法,这可能会导致打印到 stdout 的数据被截断和丢失:

// 这是一个错误用法的示例:
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exit(1);
}

这个问题的原因是因为 Node.js 中的 process.stdout 的写入有时是异步的,并且可能发生在 Node.js 事件循环的多个时间点。 但是,调用 process.exit() 会强制进程退出(在这些额外的 stdout 写入操作被执行之前)。

代码不应直接调用 process.exit(),而应设置 process.exitCode 并允许进程自然地退出(避免为事件循环调度任何额外的工作):

// 如何正确地设置退出码,同时让进程正常地退出。
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

如果由于错误条件而需要终止 Node.js 进程,则抛出未捕获的错误并允许进程相应地终止,这比调用 process.exit() 更安全。

Worker 线程中,此函数会停止当前线程(而不是当前进程)。

process.exitCode#

中英对照

当进程正常退出,或通过 process.exit() 退出且未指定退出码时,此数值会作为进程的退出码。

指定 process.exit(code) 的退出码会覆盖 process.exitCode 的任何原先的设置。

process.getegid()#

中英对照

process.getegid() 方法返回 Node.js 进程的有效数字标记的组身份(参见 getegid(2))。

if (process.getegid) {
  console.log(`当前的 gid: ${process.getegid()}`);
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。

process.geteuid()#

中英对照

process.geteuid() 方法返回 Node.js 进程的有效数字标记的用户身份(参见 geteuid(2))。

if (process.geteuid) {
  console.log(`当前的 uid: ${process.geteuid()}`);
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。

process.getgid()#

中英对照

process.getgid() 方法返回 Node.js 进程的数字标记的组身份(参见 getgid(2))。

if (process.getgid) {
  console.log(`当前的 gid: ${process.getgid()}`);
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。

process.getgroups()#

中英对照

process.getgroups() 方法返回数组,其中包含了补充的组 ID。 如果包含有效的组 ID,则 POSIX 会将其保留为未指定状态,但 Node.js 会确保它始终处于状态。

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

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。

process.getuid()#

中英对照

process.getuid() 方法返回 Node.js 进程的数字标记的用户身份(参见 getuid(2))。

if (process.getuid) {
  console.log(`当前的 uid: ${process.getuid()}`);
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。

process.hasUncaughtExceptionCaptureCallback()#

中英对照

表明是否已使用 process.setUncaughtExceptionCaptureCallback() 设置回调。

process.hrtime([time])#

中英对照

这是在 JavaScript 中引入 bigint 之前的 process.hrtime.bigint() 的传统版本。

process.hrtime() 方法返回当前时间以 [seconds, nanoseconds] 元数组表示的高精度解析值,其中 nanoseconds 是当前时间无法使用秒的精度表示的剩余部分。

time 是可选参数,传入的值是上一次调用 process.hrtime() 返回的结果,用于与当次调用做差值计算。 如果此参数传入的不是一个元数组,则会抛出 TypeError。 给此参数传入一个用户定义的数组,而不是传入上次调用 process.hrtime() 的结果,则会导致未定义的行为。

返回的时间都是相对于过去某一时刻的值,与一天中的时钟时间没有关系,因此不受制于时钟偏差。 此方法最主要的作用是衡量间隔操作的性能:

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

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

  console.log(`基准工具 ${diff[0] * NS_PER_SEC + diff[1]} 纳秒`);
  // 基准工具 1000000552 纳秒
}, 1000);

process.hrtime.bigint()#

中英对照

process.hrtime() 方法的 bigint 版本,返回当前的高精度实际时间(以纳秒为单位的 bigint 型)。

process.hrtime() 不同,它不支持额外的 time 参数,因为可以直接通过两个 bigint 相减来计算差异。

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

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

  console.log(`基准测试耗时 ${end - start} 纳秒`);
  // 基准测试耗时 1154389282 纳秒
}, 1000);

process.initgroups(user, extraGroup)#

中英对照

process.initgroups() 方法读取 /etc/group 文件,并且初始化组访问列表,该列表包括了用户所在的所有组。 该方法需要 Node.js 进程有 root 访问或者有 CAP_SETGID 能力才能操作。

删除权限时要小心:

console.log(process.getgroups());         // [ 0 ]
process.initgroups('nodeuser', 1000);   // 切换用户。
console.log(process.getgroups());         // [ 27, 30, 46, 1000, 0 ]
process.setgid(1000);                     // 删除 root 的 gid。
console.log(process.getgroups());         // [ 27, 30, 46, 1000 ]

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。 此特性在 Worker 线程中不可用。

process.kill(pid[, signal])#

中英对照

  • pid <number> 进程 ID。
  • signal <string> | <number> 要发送的信号,类型为字符串或数字。默认值: 'SIGTERM'

process.kill() 方法会发送 signalpid 标识的进程。

信号名称为字符串(比如 'SIGINT''SIGHUP')。 详见信号事件kill(2)

如果目标 pid 不存在,则该方法会抛出错误。 作为特例,信号 0 可以用于测试进程是否存在。 在 Windows 平台上,如果 pid 被用于杀死进程组,则会抛出错误。

虽然此函数的名称是 process.kill(),它其实只是信号发送器,类似于 kill 系统调用。 发送的信号可以做一些与杀死目标进程无关的事情。

process.on('SIGHUP', () => {
  console.log('收到 SIGHUP 信号');
});

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

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

当 Node.js 进程接收到 SIGUSR1 时,Node.js 会启动调试器。 参见信号事件

process.mainModule#

稳定性: 0 - 弃用: 改为使用 require.main

The process.mainModule property provides an alternative way of retrieving require.main. The difference is that if the main module changes at runtime, require.main may still refer to the original main module in modules that were required before the change occurred. Generally, it's safe to assume that the two refer to the same module.

As with require.main, process.mainModule will be undefined if there is no entry script.

process.memoryUsage()#

中英对照

process.memoryUsage() 方法会返回描述 Node.js 进程的内存使用情况(以字节为单位)的对象。

例如:

console.log(process.memoryUsage());

会返回:

{
  rss: 4935680,
  heapTotal: 1826816,
  heapUsed: 650472,
  external: 49879,
  arrayBuffers: 9386
}
  • heapTotalheapUsed 代表 V8 的内存使用情况。
  • external 代表 V8 管理的绑定到 Javascript 对象的 C++ 对象的内存使用情况。
  • rss,常驻集大小, 是为进程分配的物理内存(总分配内存的子集)的大小,包括所有的 C++ 和 JavaScript 对象与代码。
  • arrayBuffers 代表分配给 ArrayBufferSharedArrayBuffer 的内存,包括所有的 Node.js Buffer。 这也包含在 external 值中。 当 Node.js 被用作嵌入式库时,此值可能为 0,因为在这种情况下可能无法跟踪 ArrayBuffer 的分配。

当使用 Worker 线程时, rss 会是对整个进程都有效的值,而其他字段只代表当前线程。

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

中英对照

  • callback <Function>
  • ...args <any> 当调用 callback 时传入的额外参数。

process.nextTick() 会添加 callback 到下一个时间点队列。 在 JavaScript 堆栈上的当前操作运行完成之后,且允许事件循环继续之前,此队列会被完全耗尽。 如果递归地调用 process.nextTick(),则可以创建无限的循环。 有关更多背景信息,请参见事件循环指南。

console.log('开始');
process.nextTick(() => {
  console.log('下一个时间点的回调');
});
console.log('调度');
// 输出:
// 开始
// 调度
// 下一个时间点的回调

这在开发 API 时非常重要,可以在构造对象之后但在发生任何 I/O 之前,为用户提供分配事件句柄的机会:

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

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

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

// thing.startDoingStuff() 现在(而不是在之前)会被调用。

对于 100% 同步或 100% 异步的 API,此方法也非常重要。 参考以下示例:

// 警告!不要这样使用!这是不安全的!
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() 哪个会先被调用。

以下方法则更好:

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

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

process.noDeprecation#

中英对照

process.noDeprecation 属性表明是否在当前 Node.js 进程上设置了 --no-deprecation 标志。 有关此标志行为的更多信息,请参见 'warning' 事件emitWarning() 方法的文档。

process.pid#

中英对照

process.pid 属性会返回进程的 PID。

console.log(`此进程的 pid 是 ${process.pid}`);

process.platform#

中英对照

process.platform 属性会返回标识操作系统平台(Node.js 进程运行其上的)的字符串。

当前可能的值有:

  • 'aix'
  • 'darwin'
  • 'freebsd'
  • 'linux'
  • 'openbsd'
  • 'sunos'
  • 'win32'
console.log(`此平台是 ${process.platform}`);

如果 Node.js 构建于 Android 操作系统上,则也可能返回值为 'android'。 但是,Node.js 中的 Android 支持是实验性的

process.ppid#

中英对照

process.ppid 属性返回当前进程的父进程的 PID。

console.log(`父进程的 pid 是 ${process.ppid}`);

process.release#

中英对照

process.release 属性返回与当前发布相关的元数据 Object,包括源代码和源代码头文件 tarball 的 URL。

process.release 包括如下属性:

  • name <string> 此值始终为 'node'
  • sourceUrl <string> 指向一个_.tar.gz_文件的绝对 URL,包括了当前发布的源代码。
  • headersUrl<string> 指向一个_.tar.gz_文件的绝对 URL,包括了当前发布的源代码的头文件信息。 这个文件要比全部源代码文件明显小很多,可以用于编译 Node.js 原生插件。
  • libUrl <string> 指向一个_node.lib_文件的绝对 URL,匹配当前发布的结构和版本信息。此文件用于编译 Node.js 本地插件。这个属性只在 Windows 版本中存在,在其他平台中无效。
  • lts <string> 标识当前发布的 LTS 标签的字符串。

 只有 LTS 版本存在这个属性,其他所有版本类型(包括当前版本)这个属性都是 undefined。  有效值包括 LTS 发行代号(包括不再受支持的代号)。 这些代号的非穷举示例包括:

  • 'Dubnium' 用于 10.13.0 开始的 10.x LTS 版本。
  • 'Erbium' 用于 12.13.0 开始的 12.x LTS 版本。

有关其他的 LTS 发行代号,参见 Node.js 更新日志的存档

{
  name: 'node',
  lts: 'Erbium',
  sourceUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1.tar.gz',
  headersUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1-headers.tar.gz',
  libUrl: 'https://nodejs.org/download/release/v12.18.1/win-x64/node.lib'
}

从源码树的非发布版本中构建的定制版本,可能只有 name 属性有效。其他的属性不一定会存在。

process.report#

process.report is an object whose methods are used to generate diagnostic reports for the current process. Additional documentation is available in the report documentation.

process.report.compact#

Write reports in a compact format, single-line JSON, more easily consumable by log processing systems than the default multi-line format designed for human consumption.

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

process.report.directory#

Directory where the report is written. The default value is the empty string, indicating that reports are written to the current working directory of the Node.js process.

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

process.report.filename#

Filename where the report is written. If set to the empty string, the output filename will be comprised of a timestamp, PID, and sequence number. The default value is the empty string.

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

process.report.getReport([err])#

  • err <Error> A custom error used for reporting the JavaScript stack.
  • Returns: <Object>

Returns a JavaScript Object representation of a diagnostic report for the running process. The report's JavaScript stack trace is taken from err, if present.

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

// Similar to process.report.writeReport()
const fs = require('fs');
fs.writeFileSync(util.inspect(data), 'my-report.log', 'utf8');

Additional documentation is available in the report documentation.

process.report.reportOnFatalError#

稳定性: 1 - 实验

If true, a diagnostic report is generated on fatal errors, such as out of memory errors or failed C++ assertions.

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

process.report.reportOnSignal#

If true, a diagnostic report is generated when the process receives the signal specified by process.report.signal.

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

process.report.reportOnUncaughtException#

If true, a diagnostic report is generated on uncaught exception.

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

process.report.signal#

The signal used to trigger the creation of a diagnostic report. Defaults to 'SIGUSR2'.

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

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

  • filename <string> Name of the file where the report is written. This should be a relative path, that will be appended to the directory specified in process.report.directory, or the current working directory of the Node.js process, if unspecified.

  • err <Error> A custom error used for reporting the JavaScript stack.

  • Returns: <string> Returns the filename of the generated report.

Writes a diagnostic report to a file. If filename is not provided, the default filename includes the date, time, PID, and a sequence number. The report's JavaScript stack trace is taken from err, if present.

process.report.writeReport();

Additional documentation is available in the report documentation.

process.resourceUsage()#

  • Returns: <Object> the resource usage for the current process. All of these values come from the uv_getrusage call which returns a uv_rusage_t struct.
    • userCPUTime <integer> maps to ru_utime computed in microseconds. It is the same value as process.cpuUsage().user.
    • systemCPUTime <integer> maps to ru_stime computed in microseconds. It is the same value as process.cpuUsage().system.
    • maxRSS <integer> maps to ru_maxrss which is the maximum resident set size used in kilobytes.
    • sharedMemorySize <integer> maps to ru_ixrss but is not supported by any platform.
    • unsharedDataSize <integer> maps to ru_idrss but is not supported by any platform.
    • unsharedStackSize <integer> maps to ru_isrss but is not supported by any platform.
    • minorPageFault <integer> maps to ru_minflt which is the number of minor page faults for the process, see this article for more details.
    • majorPageFault <integer> maps to ru_majflt which is the number of major page faults for the process, see this article for more details. This field is not supported on Windows.
    • swappedOut <integer> maps to ru_nswap but is not supported by any platform.
    • fsRead <integer> maps to ru_inblock which is the number of times the file system had to perform input.
    • fsWrite <integer> maps to ru_oublock which is the number of times the file system had to perform output.
    • ipcSent <integer> maps to ru_msgsnd but is not supported by any platform.
    • ipcReceived <integer> maps to ru_msgrcv but is not supported by any platform.
    • signalsCount <integer> maps to ru_nsignals but is not supported by any platform.
    • voluntaryContextSwitches <integer> maps to ru_nvcsw which is the number of times a CPU context switch resulted due to a process voluntarily giving up the processor before its time slice was completed (usually to await availability of a resource). This field is not supported on Windows.
    • involuntaryContextSwitches <integer> maps to ru_nivcsw which is the number of times a CPU context switch resulted due to a higher priority process becoming runnable or because the current process exceeded its time slice. This field is not supported on Windows.
console.log(process.resourceUsage());
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/

process.send(message[, sendHandle[, options]][, callback])#

中英对照

  • message <Object>
  • sendHandle <net.Server> | <net.Socket>
  • options <Object> 用于参数化特定类型的句柄的发送。options 支持以下属性:
    • keepOpen <boolean> 当传递 net.Socket 实例时可以使用的值。 当为 true 时,则 socket 在发送的过程中会保持打开。 默认值: false
  • callback <Function>
  • 返回: <boolean>

如果 Node.js 是使用 IPC 通道衍生的,则可以使用 process.send() 方法发送消息到父进程。 消息会被接收为父进程的 ChildProcess 对象上的 'message' 事件。

如果 Node.js 不是通过 IPC 通道衍生的,则 process.send 会是 undefined

消息会进行序列化和解析。 生成的消息可能与最初发送的消息不同。

process.setegid(id)#

中英对照

process.setegid() 方法为进程设置有效的组标识。(参见 setegid(2))。 id 可以传入数字 ID 或组名字符串。 如果指定了组名,则此方法在解析关联的数字 ID 时会阻塞。

if (process.getegid && process.setegid) {
  console.log(`当前的 gid: ${process.getegid()}`);
  try {
    process.setegid(501);
    console.log(`新的 gid: ${process.getegid()}`);
  } catch (err) {
    console.log(`无法设置 gid: ${err}`);
  }
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。 此特性在 Worker 线程中不可用。

process.seteuid(id)#

中英对照

process.seteuid() 方法为进程设置有效的用户标识。(参见 seteuid(2))。 id 可以传入数字 ID 或用户名字符串。 如果指定了用户名,则此方法在解析关联的数字 ID 时会阻塞。

if (process.geteuid && process.seteuid) {
  console.log(`当前的 uid: ${process.geteuid()}`);
  try {
    process.seteuid(501);
    console.log(`新的 uid: ${process.geteuid()}`);
  } catch (err) {
    console.log(`无法设置 uid: ${err}`);
  }
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。 此特性在 Worker 线程中不可用。

process.setgid(id)#

中英对照

process.setgid() 方法为进程设置组标识。(参见 setgid(2))。 id 可以传入数字 ID 或组名字符串。 如果指定了组名,则此方法在解析关联的数字 ID 时会阻塞。

if (process.getgid && process.setgid) {
  console.log(`当前的 gid: ${process.getgid()}`);
  try {
    process.setgid(501);
    console.log(`新的 gid: ${process.getgid()}`);
  } catch (err) {
    console.log(`无法设置 gid: ${err}`);
  }
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。 此特性在 Worker 线程中不可用。

process.setgroups(groups)#

The process.setgroups() method sets the supplementary group IDs for the Node.js process. This is a privileged operation that requires the Node.js process to have root or the CAP_SETGID capability.

The groups array can contain numeric group IDs, group names, or both.

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

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

process.setuid(id)#

中英对照

process.setuid(id) 方法为进程设置用户标识。(参见 setuid(2))。 id 可以传入数字 ID 或用户名字符串。 如果指定了用户名,则此方法在解析关联的数字 ID 时会阻塞。

if (process.getuid && process.setuid) {
  console.log(`当前的 uid: ${process.getuid()}`);
  try {
    process.setuid(501);
    console.log(`新的 uid: ${process.getuid()}`);
  } catch (err) {
    console.log(`无法设置 uid: ${err}`);
  }
}

这个函数只在 POSIX 平台有效(在 Windows 或 Android 平台无效)。 此特性在 Worker 线程中不可用。

process.setUncaughtExceptionCaptureCallback(fn)#

The process.setUncaughtExceptionCaptureCallback() function sets a function that will be invoked when an uncaught exception occurs, which will receive the exception value itself as its first argument.

If such a function is set, the 'uncaughtException' event will not be emitted. If --abort-on-uncaught-exception was passed from the command line or set through v8.setFlagsFromString(), the process will not abort. Actions configured to take place on exceptions such as report generations will be affected too

To unset the capture function, process.setUncaughtExceptionCaptureCallback(null) may be used. Calling this method with a non-null argument while another capture function is set will throw an error.

Using this function is mutually exclusive with using the deprecated domain built-in module.

process.stderr#

中英对照

process.stderr 属性会返回连接到 stderr (文件描述符 2) 的流。 它是一个 net.Socket(也就是 Duplex 流),除非文件描述符 2 指向文件(在这种情况下它是一个 Writable 流)。

process.stderr 与其他的 Node.js 流有重大区别。 详见进程 I/O 的注意事项

process.stderr.fd#

中英对照

此属性指向 process.stderr 的底层文件描述符的值。 该值固定为 2。 在 Worker 线程中,此字段不存在。

process.stdin#

中英对照

process.stdin 属性会返回连接到 stdin (文件描述符 0) 的流。 它是一个 net.Socket(也就是 Duplex 流),除非文件描述符 0 指向文件(在这种情况下它是一个 Readable 流)。

关于如何从 stdin 中读取,详见 readable.read()

作为 Duplex 流, process.stdin 也可以在“旧”模式中使用,该模式与在 v0.10 之前为 Node.js 编写的脚本兼容。 详见流的兼容性

在“旧”的流模式中,默认情况下 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.stdinprocess.stdout

process.stdin.pipe(process.stdout);

process.stdout 与其他的 Node.js 流有重大区别。 详见进程 I/O 的注意事项

process.stdout.fd#

中英对照

此属性指向 process.stdout 的底层文件描述符的值。 该值固定为 1。 在 Worker 线程中,此字段不存在。

进程 I/O 的注意事项#

中英对照

process.stdoutprocess.stderr 与其他 Node.js 流有重大不同:

  1. 它们分别被用于 console.log()console.error() 内部。
  2. 写操作是否为同步,取决于连接到的流以及操作系统是 Windows 还是 POSIX:
    • 文件:在 Windows 和 POSIX 上都是同步的。
    • TTY(终端):在 Windows 上是异步的,在 POSIX 上是同步的。
    • 管道(以及 socket):在 Windows 上是同步的,在 POSIX 上是异步的。

这些行为部分是历史原因,改变它们可能导致向后不兼容,而且它们的行为也符合部分用户的期望。

同步的写操作可以避免一些问题,比如 console.log()console.error() 写入的输出被不符合预期地交错,或者在异步的写入完成前调用了 process.exit() 导致根本没写入。 详见 process.exit()

注意,同步的写入会阻塞事件循环直到写入完成。 在输出到文件的情况下,这可能几乎是瞬时的,但当系统处于高负载时,管道的接收端不被读取,或者终端或文件系统速度缓慢,这可能使事件循环经常被长时间阻塞,从而对性能产生严重的负面影响。 当写入到交互的终端会话时,这可能不是个问题,但当写入生产日志到进程的输出流时,则要特别留心。

如果要检查一个流是否连接到了 TTY 上下文, 则检查 isTTY 属性。

例如:

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

详见 TTY 文档。

process.throwDeprecation#

中英对照

process.throwDeprecation 的初始值表明是否在当前的 Node.js 进程上设置了 --throw-deprecation 标志。 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');
抛出:
[DeprecationWarning: test] { name: 'DeprecationWarning' }

process.title#

中英对照

process.title 属性返回当前进程标题(即返回 ps 的当前值)。 为 process.title 分配新值会修改 ps 的当前值。

当分配新值时,不同的平台会对标题施加不同的最大长度限制。 通常这种限制是相当有限的。 例如,在 Linux 和 macOS 上, process.title 仅限于二进制名称的大小加上命令行参数的长度,因为设置 process.title 会覆盖进程的 argv 内存。 Node.js 的 v0.8, 通过覆盖 environ 允许内存较长的过程标题字符串,但是这在一些(相当模糊的)可能是不安全的并且令人困惑情况下。

Assigning a value to process.title might not result in an accurate label within process manager applications such as macOS Activity Monitor or Windows Services Manager.

process.traceDeprecation#

The process.traceDeprecation property indicates whether the --trace-deprecation flag is set on the current Node.js process. See the documentation for the 'warning' event and the emitWarning() method for more information about this flag's behavior.

process.umask()#

稳定性: 0 - 弃用. Calling process.umask() with no argument causes the process-wide umask to be written twice. This introduces a race condition between threads, and is a potential security vulnerability. There is no safe, cross-platform alternative API.

process.umask() returns the Node.js process's file mode creation mask. Child processes inherit the mask from the parent process.

process.umask(mask)#

中英对照

process.umask(mask) 会设置 Node.js 进程的文件模式的创建掩码。 子进程从父进程继承掩码。 返回上一个掩码。

const newmask = 0o022;
const oldmask = process.umask(newmask);
console.log(
  `将 umask 从 ${oldmask.toString(8)} 更改为 ${newmask.toString(8)}`
);

Worker 线程中, process.umask(mask) 会抛出异常。

process.uptime()#

中英对照

process.uptime() 方法会返回当前 Node.js 进程已运行的时长(以秒为单位)。

返回的值包括秒的分数。 使用 Math.floor() 可以获得秒的整数。

process.version#

中英对照

process.version 属性包含 Node.js 版本的字符串。

console.log(`版本: ${process.version}`);
// 版本: v14.8.0

若要获取不带前缀 v 的版本字符串,则使用 process.versions.node

process.versions#

中英对照

process.versions 属性会返回列出 Node.js 及其依赖的版本字符串的对象。 process.versions.modules 表明当前的 ABI 版本,其会随着 C++ API 的变化而增加。 Node.js 会拒绝加载使用不同的模块 ABI 版本编译的模块。

console.log(process.versions);

会符合类似以下的对象:

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

退出码#

中英对照

当没有异步的操作在等待处理时,则 Node.js 会以状态码 0 正常地退出。 其他情况下,会用如下的状态码:

  • 1 未捕获的致命异常:有未捕获的异常,并且没被域或 'uncaughtException' 事件句柄处理。
  • 2:未被使用(被 Bash 预留用于内置的误用)。
  • 3 内部的 JavaScript 解析错误:Node.js 引导进程内部中的 JavaScript 源代码造成的解析错误。 这是非常少见的, 一般只会在开发 Node.js 本身的时候出现。
  • 4 内部的 JavaScript 执行失败:Node.js 引导进程内部中的 JavaScript 源代码在执行时返回函数值失败。 这是非常少见的, 一般只会在开发 Node.js 本身的时候出现。
  • 5 致命的错误:在 V8 中有致命的错误。 通常会以 FATAL ERROR 为前缀打印消息到 stderr。
  • 6 非函数的内部异常句柄:有未捕获的异常,但是内部的致命异常句柄被设置为非函数且不能被调用。
  • 7 内部异常句柄运行时失败:有未捕获的异常,且内部的致命异常句柄函数在试图处理异常时本身抛出了错误。 这是可能发生的,比如,'uncaughtException' 或者 domain.on('error') 句柄抛出错误。
  • 8:未被使用。在之前的 Node.js 版本中,退出码 8 有时候表示未被捕获的异常。
  • 9 无效的参数:指定了未知的选项,或者没给必需要的选项提供值。
  • 10 内部的 JavaScript 运行时失败:当引导函数被调用时,Node.js 引导进程内部中的 JavaScript 源代码抛出错误。 这是非常少见的, 一般只会在开发 Node.js 本身的时候出现。
  • 12 无效的调试参数--inspect 和/或 --inspect-brk 选项已设置,但选择的端口号无效或不可用。
  • 13 未完成的顶层等待: await 被用于顶层代码中的函数之外,但是传递的 Promise 从未被解决。
  • >128 信号退出:如果 Node.js 接收到致命信号, 比如 SIGKILLSIGHUP,则其退出码会是 128 加上信号码的值。 这是标准 POSIX 的实践,因为退出码被定义为 7 位整数,并且信号退出设置了高位,然后包含信号码的值。 例如,信号 SIGABRT 的值为 6,因此期望的退出码会是 128 + 6134