Node.js v18.7.0 文档

进程事件#

中英对照

process 对象是 EventEmitter 的实例。

'beforeExit' 事件#

中英对照

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

'disconnect' 事件#

中英对照

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

'exit' 事件#

中英对照

当 Node.js 进程由于以下任一原因即将退出时，则会触发 'exit' 事件：

'message' 事件#

中英对照

如果 Node.js 进程是使用 IPC 通道衍生（参见子进程和集群文档），则每当子进程收到父进程使用 childprocess.send() 发送的消息时，就会触发 'message' 事件。

'multipleResolves' 事件#

中英对照

每当 Promise 满足以下任一条件时，就会触发 'multipleResolves' 事件：

'rejectionHandled' 事件#

中英对照

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

'uncaughtException' 事件#

中英对照

当未捕获的 JavaScript 异常一直冒泡回到事件循环时，则会触发 'uncaughtException' 事件。 默认情况下，Node.js 通过将堆栈跟踪打印到 stderr 并以代码 1 退出，覆盖任何先前设置的 process.exitCode 来处理此类异常。 为 'uncaughtException' 事件添加句柄会覆盖此默认行为。 或者，更改 'uncaughtException' 处理程序中的 process.exitCode，这将导致进程以提供的退出码退出。 否则，在存在此类句柄的情况下，进程将以 0 退出。

注意: 正确使用 'uncaughtException'#

中英对照

'uncaughtException' 是用于异常处理的粗略机制，仅用作最后的手段。 事件_不应该_用作 On Error Resume Next 的等价物。 未处理的异常本质上意味着应用程序处于未定义状态。 在没有从异常中正确恢复的情况下尝试恢复应用程序代码可能会导致其他不可预见和不可预测的问题。

'uncaughtExceptionMonitor' 事件#

中英对照

'uncaughtExceptionMonitor' 事件在 'uncaughtException' 事件触发或通过 process.setUncaughtExceptionCaptureCallback() 安装的钩子被调用之前触发。

'unhandledRejection' 事件#

中英对照

每当 Promise 被拒绝并且在事件循环的一个轮询内没有错误句柄附加到承诺时，则会触发 'unhandledRejection' 事件。 使用 Promise 进行编程时，异常被封装为“被拒绝的 promise”。 拒绝可以使用 promise.catch() 捕获和处理，并通过 Promise 链传播。 'unhandledRejection' 事件对于检测和跟踪尚未处理的被拒绝的 promise 很有用。

'warning' 事件#

中英对照

每当 Node.js 触发进程警告时，则会触发 'warning' 事件。

'worker' 事件#

中英对照

创建新的 <Worker> 线程后会触发 'worker' 事件。

触发自定义的告警#

中英对照

请参阅 process.emitWarning() 方法以发出自定义或特定于应用程序的警告。

Node.js 警告的名称#

中英对照

Node.js 触发的警告类型（由 name 属性标识）没有严格的指导方针。 可以随时添加新类型的警告。 一些最常见的警告类型包括：

信号事件#

中英对照

当 Node.js 进程收到信号时，则将触发信号事件。 有关标准 POSIX 信号名称（例如 'SIGINT'、'SIGHUP' 等）的列表，请参阅 signal(7)。

process.abort()#

中英对照

process.abort() 方法会导致 Node.js 进程立即退出并生成一个核心文件。

process.allowedNodeEnvironmentFlags#

中英对照

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

process.arch#

中英对照

为其编译 Node.js 二进制文件的操作系统 CPU 架构。 可能的值为：'arm'、'arm64'、'ia32'、'mips'、'mipsel'、'ppc'、'ppc64'、's390'、's390x'、以及 'x64'。

process.argv#

中英对照

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

process.argv0#

中英对照

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

process.channel#

中英对照

如果 Node.js 进程是使用 IPC 通道衍生（参见子进程文档），则 process.channel 属性是对 IPC 通道的引用。 如果不存在 IPC 通道，则此属性为 undefined。

process.channel.ref()#

中英对照

如果之前已调用过 .unref()，则此方法使 IPC 通道保持进程的事件循环运行。

process.channel.unref()#

中英对照

此方法使 IPC 通道不会保持进程的事件循环运行，并且即使在通道打开时也让它完成。

process.chdir(directory)#

中英对照

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

process.config#

中英对照

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

process.connected#

中英对照

如果 Node.js 进程使用 IPC 通道衍生（参见子进程和集群文档），则只要 IPC 通道连接，process.connected 属性将返回 true，并在调用 process.disconnect() 后返回 false。

process.cpuUsage([previousValue])#

中英对照

process.cpuUsage() 方法在具有属性 user 和 system 的对象中返回当前进程的用户和系统 CPU 时间使用情况，其值为微秒值（百万分之一秒）。 这些值分别测量在用户和系统代码中花费的时间，如果多个 CPU 内核为此进程执行工作，则最终可能会大于实际经过的时间。

process.cwd()#

中英对照

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

process.debugPort#

中英对照

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

process.disconnect()#

中英对照

如果 Node.js 进程是使用 IPC 通道衍生（参见子进程和集群文档），则 process.disconnect() 方法将关闭通往父进程的 IPC 通道，一旦没有其他连接使其保持活动状态，则允许子进程正常退出。

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

中英对照

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

process.emitWarning(warning[, options])#

中英对照

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

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

中英对照

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

避免重复警告#

中英对照

作为最佳实践，每个进程只应触发一次警告。 为此，则将 emitWarning() 放在布尔值后面。

process.env#

中英对照

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

process.execArgv#

中英对照

process.execArgv 属性返回 Node.js 进程启动时传入的一组特定于 Node.js 的命令行选项。 这些选项不会出现在 process.argv 属性返回的数组中，也不包括 Node.js 可执行文件、脚本名称或脚本名称后面的任何选项。 这些选项可用于衍生与父进程具有相同执行环境的子进程。

process.execPath#

中英对照

process.execPath 属性返回启动 Node.js 进程的可执行文件的绝对路径名。 符号链接（如果有）会被解析。

process.exit([code])#

中英对照

process.exit() 方法指示 Node.js 以 code 的退出状态同步终止进程。 如果省略 code，则退出将使用“成功”代码 0 或 process.exitCode 的值（如果已设置）。 直到所有 'exit' 事件监听器都被调用，Node.js 才会终止。

process.exitCode#

中英对照

当进程正常退出或通过 process.exit() 退出而不指定代码时，将作为进程退出码的数字。

process.getActiveResourcesInfo()#

中英对照

process.getActiveResourcesInfo() 方法返回字符串数组，其中包含当前保持事件循环活动的活动资源的类型。

process.getegid()#

中英对照

process.getegid() 方法返回 Node.js 进程的数字有效群组标识。 （见 getegid(2)。）

process.geteuid()#

中英对照

process.geteuid() 方法返回进程的数字有效用户身份。 （见 geteuid(2)。）

process.getgid()#

中英对照

process.getgid() 方法返回进程的数字群组标识。 （见 getgid(2)。）

process.getgroups()#

中英对照

process.getgroups() 方法返回带有补充组 ID 的数组。 POSIX 不指定是否包含有效组 ID，但 Node.js 确保它始终包含。

process.getuid()#

中英对照

process.getuid() 方法返回进程的数字用户标识。 （见 getuid(2)。）

process.hasUncaughtExceptionCaptureCallback()#

中英对照

指示是否已使用 process.setUncaughtExceptionCaptureCallback() 设置回调。

process.hrtime([time])#

中英对照

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

process.hrtime.bigint()#

中英对照

process.hrtime() 方法的 bigint 版本以纳秒为单位返回当前高解析度实时作为 bigint。

process.initgroups(user, extraGroup)#

中英对照

process.initgroups() 方法读取 /etc/group 文件并使用用户所属的所有组初始化组访问列表。 这是一个特权操作，要求 Node.js 进程具有 root 访问权限或 CAP_SETGID 能力。

process.kill(pid[, signal])#

中英对照

process.kill() 方法将 signal 发送到由 pid 标识的进程。

process.mainModule#

中英对照

process.mainModule 属性提供了另一种检索 require.main 的方法。 不同之处在于，如果主模块在运行时发生更改，则 require.main 可能仍会引用更改发生前所需模块中的原始主模块。 通常，可以安全地假设两者指的是同一个模块。

process.memoryUsage()#

中英对照

返回描述 Node.js 进程的内存使用量（以字节为单位）的对象。

process.memoryUsage.rss()#

中英对照

process.memoryUsage.rss() 方法返回以字节为单位表示驻留集大小的整数 (RSS)。

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

中英对照

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

何时使用 queueMicrotask() 与 process.nextTick()#

中英对照

queueMicrotask() API 是 process.nextTick() 的替代方案，它还使用用于执行 then、catch 和 finally 处理程序的相同微任务队列来延迟函数的执行。 在 Node.js 中，每次“下一个滴答队列”被排空时，微任务队列也会立即排空。

process.noDeprecation#

中英对照

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

process.pid#

中英对照

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

process.platform#

中英对照

process.platform 属性返回用于标识编译 Node.js 二进制文件的操作系统平台的字符串。

process.ppid#

中英对照

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

process.release#

中英对照

process.release 属性返回 Object，其中包含与当前版本相关的元数据，包括源 tarball 和 headers-only tarball 的网址。

process.report#

中英对照

process.report 是一个对象，其方法用于为当前进程生成诊断报告。 报告文档中提供了额外文档。

process.report.compact#

中英对照

以紧凑的单行 JSON 格式编写报告，与专为人类使用而设计的默认多行格式相比，日志处理系统更易于使用。

process.report.directory#

中英对照

写入报告的目录。 默认值为空字符串，表示将报告写入 Node.js 进程的当前工作目录。

process.report.filename#

中英对照

写入报告的文件名。 如果设置为空字符串，则输出文件名将由时间戳、PID 和序列号组成。 默认值为空字符串。

process.report.getReport([err])#

中英对照

返回正在运行的进程的诊断报告的 JavaScript 对象表示形式。 报告的 JavaScript 堆栈跟踪取自 err（如果存在）。

process.report.reportOnFatalError#

中英对照

如果为 true，则会生成有关致命错误（例如内存不足错误或 C++ 断言失败）的诊断报告。

process.report.reportOnSignal#

中英对照

如果为 true，则当进程接收到 process.report.signal 指定的信号时生成诊断报告。

process.report.reportOnUncaughtException#

中英对照

如果为 true，则针对未捕获的异常生成诊断报告。

process.report.signal#

中英对照

用于触发诊断报告创建的信号。 默认为 'SIGUSR2'。

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

中英对照

将诊断报告写入文件。 如果未提供 filename，则默认文件名包括日期、时间、PID 和序列号。 报告的 JavaScript 堆栈跟踪取自 err（如果存在）。

process.resourceUsage()#

中英对照

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

中英对照

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

process.setegid(id)#

中英对照

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

process.seteuid(id)#

中英对照

process.seteuid() 方法设置进程的有效用户身份。 （请参阅 seteuid(2)。） id 可以作为数字 ID 或用户名字符串传入。 如果指定了用户名，则该方法在解析关联的数字 ID 时会阻塞。

process.setgid(id)#

中英对照

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

process.setgroups(groups)#

中英对照

process.setgroups() 方法为 Node.js 进程设置补充群组 ID。 这是一个特权操作，需要 Node.js 进程具有 root 或 CAP_SETGID 能力。

process.setuid(id)#

中英对照

process.setuid(id) 方法设置进程的用户身份。 （请参阅 setuid(2)。） id 可以作为数字 ID 或用户名字符串传入。 如果指定了用户名，则该方法在解析关联的数字 ID 时会阻塞。

process.setSourceMapsEnabled(val)#

中英对照

此函数启用或禁用对堆栈跟踪的 Source Map v3 的支持。

process.setUncaughtExceptionCaptureCallback(fn)#

中英对照

process.setUncaughtExceptionCaptureCallback() 函数设置一个函数，当发生未捕获的异常时将调用该函数，该函数将接收异常值本身作为其第一个参数。

process.stderr#

中英对照

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

process.stderr.fd#

中英对照

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

process.stdin#

中英对照

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

process.stdin.fd#

中英对照

该属性指的是 process.stdin 的底层文件描述符的值。 该值固定为 0。 在 Worker 线程中，该字段不存在。

process.stdout#

中英对照

process.stdout 属性返回连接到 stdout (文件描述符 1) 的流。 它是 net.Socket（也就是 Duplex 流），除非文件描述符 1 指向文件，在这种情况下它是 Writable 流。

process.stdout.fd#

中英对照

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

进程 I/O 的注意事项#

中英对照

process.stdout 和 process.stderr 在重要方面与其他 Node.js 流不同：

process.throwDeprecation#

中英对照

process.throwDeprecation 的初始值表示当前 Node.js 进程是否设置了 --throw-deprecation 标志。 process.throwDeprecation 是可变的，因此可能会在运行时更改弃用警告是否导致错误。 有关更多信息，请参阅 'warning' 事件和 emitWarning() 方法的文档。

process.title#

中英对照

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

process.traceDeprecation#

中英对照

process.traceDeprecation 属性指示是否在当前 Node.js 进程上设置了 --trace-deprecation 标志。 有关此标志行为的更多信息，请参阅 'warning' 事件和 emitWarning() 方法的文档。

process.umask()#

中英对照

process.umask() 返回 Node.js 进程的文件模式创建掩码。 子进程从父进程继承掩码。

process.umask(mask)#

中英对照

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

process.uptime()#

中英对照

process.uptime() 方法返回当前 Node.js 进程已经运行的秒数。

process.version#

中英对照

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

process.versions#

中英对照

process.versions 属性返回对象，其中列出了 Node.js 的版本字符串及其依赖项。 process.versions.modules 表示当前的 ABI 版本，每当 C++ API 更改时都会增加。 Node.js 将拒绝加载针对不同模块 ABI 版本编译的模块。

退出码#

中英对照

当没有更多异步操作挂起时，Node.js 通常会以 0 状态代码退出。 在其他情况下使用以下状态代码：