Node.js v16.19.1 文档


目录

CLI 命令行#

中英对照

Node.js 具有各种各样的命令行选项。 这些选项暴露了内置调试、多种执行脚本的方式、以及其他有用的运行时选项。

要在终端中将本文档作为手册页查看,则运行 man node

概要#

中英对照

node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]

node inspect [<program-entry-point> | -e "script" | <host>:<port>] …

node --v8-options

不带参数执行以启动交互式解释器

有关 node inspect 的更多信息,请参阅调试器文档。

程序入口点#

中英对照

程序入口点是类似说明符的字符串。 如果字符串不是绝对路径,则解析为当前工作目录的相对路径。 然后由 CommonJS 模块加载器解析该路径。 如果没有找到对应的文件,则抛出错误。

如果找到文件,则其路径将在以下任一条件下传给 ECMAScript 模块加载器

  • 该程序以命令行标志启动,该标志强制使用 ECMAScript 模块加载器加载入口点。
  • 该文件的扩展名为 .mjs
  • 该文件没有 .cjs 扩展名,并且最近的父 package.json 文件包含值为 "module" 的顶层 "type" 字段。

否则,使用 CommonJS 模块加载器加载文件。 参阅模块加载器了解更多详细信息。

ECMAScript 模块加载器入口点警告#

中英对照

当加载 ECMAScript 模块加载器加载程序入口点时,node 命令将仅接受使用 .js.mjs、或 .cjs 扩展名的文件作为输入;当启用 --experimental-wasm-modules 时,则使用 .wasm 扩展名。

选项#

中英对照

所有选项,包括 V8 选项,都允许用破折号 (-) 或下划线 (_) 分隔单词。 例如,--pending-deprecation 等价于 --pending_deprecation

如果接受单个值的选项(例如 --max-http-header-size)被多次传入,则使用最后传入的值。 来自命令行的选项优先于通过 NODE_OPTIONS 环境变量传入的选项。

-#

中英对照

标准输入的别名。 类似于在其他命令行工具中使用 -,这意味着脚本是从标准输入读取的,其余的选项将传给该脚本。

--#

中英对照

指示 node 选项的结束。 将其余参数传给脚本。 如果在此之前没有提供脚本文件名或评估/打印脚本,则下一个参数用作脚本文件名。

--abort-on-uncaught-exception#

中英对照

中止而不是退出会导致使用调试器(例如 lldbgdbmdb)生成用于事后分析的核心文件。

如果传入了此标志,则该行为仍然可以设置为不通过 process.setUncaughtExceptionCaptureCallback() 中止(以及通过使用使用它的 node:domain 模块)

--completion-bash#

中英对照

为 Node.js 打印可源代码的 bash 完成脚本。

$ node --completion-bash > node_bash_completion
$ source node_bash_completion

-C=condition, --conditions=condition#

中英对照

稳定性: 1 - 实验

启用对自定义的条件导出解析条件的实验性支持。

允许任意数量的自定义字符串条件名称。

"node""default""import""require" 的默认 Node.js 条件将始终按照定义应用。

例如,要运行具有 "development" 解析的模块:

$ node -C=development app.js

--cpu-prof#

中英对照

稳定性: 1 - 实验

启动时开始 V8 CPU 分析器,并且在退出前将 CPU 分析文件写入磁盘。

如果未指定--cpu-prof-dir,则生成的分析文件放在当前工作目录中。

如果未指定 --cpu-prof-name,则生成的分析文件名为 CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile

$ node --cpu-prof index.js
$ ls *.cpuprofile
CPU.20190409.202950.15293.0.0.cpuprofile

--cpu-prof-dir#

中英对照

稳定性: 1 - 实验

指定放置 --cpu-prof 生成的 CPU 分析文件的目录

默认值由 --diagnostic-dir 命令行选项控制。

--cpu-prof-interval#

中英对照

稳定性: 1 - 实验

--cpu-prof 生成的 CPU 分析文件指定以微秒为单位的采样间隔。 默认为 1000 微秒。

--cpu-prof-name#

中英对照

稳定性: 1 - 实验

指定 --cpu-prof 生成的 CPU 分析文件的文件名。

--diagnostic-dir=directory#

中英对照

设置写入所有诊断输出文件的目录。 默认为当前工作目录。

影响默认输出目录:

--disable-proto=mode#

中英对照

禁用 Object.prototype.__proto__ 属性。 如果 modedelete,则该属性将被完全删除。 如果 modethrow,则访问该属性会使用代码 ERR_PROTO_ACCESS 抛出异常。

--disallow-code-generation-from-strings#

中英对照

使从字符串生成代码的 evalnew Function 等内置语言功能抛出异常。 这不会影响 Node.js node:vm 模块。

--dns-result-order=order#

中英对照

dns.lookup()dnsPromises.lookup() 中设置 verbatim 的默认值。 该值可能是:

  • ipv4first: 设置默认的 verbatimfalse
  • verbatim: 设置默认的 verbatimtrue

默认为 ipv4first,并且 dns.setDefaultResultOrder() 的优先级高于 --dns-result-order

--enable-fips#

中英对照

在启动时启用符合 FIPS 的加密。 (需要针对兼容 FIPS 的 OpenSSL 构建 Node.js。)

--enable-source-maps#

中英对照

启用 Source Map v3 对堆栈跟踪的支持。

当使用转译器(例如 TypeScript)时,应用程序抛出的堆栈跟踪会引用转译后的代码,而不是原始的源位置。 --enable-source-maps 启用源映射缓存并尽最大努力报告相对于原始源文件的堆栈跟踪。

覆盖 Error.prepareStackTrace 可防止 --enable-source-maps 修改堆栈跟踪。

注意,启用源映射会在访问 Error.stack 时给您的应用程序引入延迟。 如果您在应用程序中频繁访问 Error.stack,则考虑 --enable-source-maps 的性能影响

--experimental-fetch#

中英对照

启用对 Fetch API 的实验性支持。

--experimental-global-customevent#

中英对照

在全局作用域内公开 CustomEvent Web API

--experimental-global-webcrypto#

中英对照

在全局作用域内公开 Web 加密 API

--experimental-import-meta-resolve#

中英对照

启用实验性 import.meta.resolve() 支持。

--experimental-loader=module#

中英对照

指定自定义的实验的 ECMAScript 模块加载器modulemodule 可以是任何作为 import 说明符接受的字符串。

--experimental-network-imports#

中英对照

稳定性: 1 - 实验

import 说明符中启用对 https: 协议的实验性支持。

--experimental-policy#

中英对照

使用指定的文件作为安全策略。

--no-experimental-repl-await#

中英对照

使用此标志在交互式解释器中禁用顶层等待。

--experimental-specifier-resolution=mode#

中英对照

设置解析 ES 模块说明符的解析算法。 有效选项为 explicitnode

默认为 explicit,需要提供模块的完整路径。 node 模式支持可选文件扩展名和导入具有索引文件的目录的能力。

请参阅自定义的 ESM 说明符解析以获取示例用法。

--experimental-vm-modules#

中英对照

node:vm 模块中启用实验性 ES 模块支持。

--experimental-wasi-unstable-preview1#

中英对照

启用实验性 WebAssembly 系统接口 (WASI) 支持。

--experimental-wasm-modules#

中英对照

启用实验性 WebAssembly 模块支持。

--force-context-aware#

中英对照

禁用加载不是上下文感知的原生插件。

--force-fips#

中英对照

在启动时强制执行符合 FIPS 的加密。 (不能从脚本代码中禁用。)(与 --enable-fips 要求相同。)

--frozen-intrinsics#

中英对照

稳定性: 1 - 实验

启用像 ArrayObject 这样的实验性冻结内在函数。

仅支持根上下文。 不能保证 globalThis.Array 确实是默认的内在引用。 代码可能会在此标志下被破坏。

为了允许添加 polyfill,--require 在冻结内在函数之前运行。

--force-node-api-uncaught-exceptions-policy#

中英对照

在 Node-API 异步回调上强制执行 uncaughtException 事件。

为防止现有插件使进程崩溃,默认情况下未启用此标志。 将来,这个标志将默认启用以强制执行正确的行为。

--heapsnapshot-near-heap-limit=max_count#

中英对照

稳定性: 1 - 实验

当 V8 堆使用量接近堆限制时,将 V8 堆快照写入磁盘。 count 应该是非负整数(在这种情况下,Node.js 将不超过 max_count 的快照写入磁盘)。

当生成快照时,可能会触发垃圾回收并降低堆使用率。 因此,在 Node.js 实例最终内存不足之前,可能会将多个快照写入磁盘。 可以比较这些堆快照以确定在拍摄连续快照期间正在分配哪些对象。 不能保证 Node.js 会准确地将 max_count 个快照写入磁盘,但是当 max_count 大于 0 时,它会尽量在 Node.js 实例耗尽内存之前生成至少一个和最多 max_count 个快照。

生成 V8 快照需要时间和内存(由 V8 堆管理的内存和 V8 堆外的原生内存)。 堆越大,需要的资源越多。 Node.js 会调整 V8 堆以适应额外的 V8 堆内存开销,并尽量避免耗尽进程可用的所有内存。 当进程使用的内存超过系统认为合适的内存时,该进程可能会被系统突然终止,具体取决于系统配置。

$ node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.js
Wrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshot
Wrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshot
Wrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot

<--- Last few GCs --->

[49580:0x110000000]     4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms  (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed
[49580:0x110000000]     4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms  (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
....

--heapsnapshot-signal=signal#

中英对照

启用信号句柄,当接收到指定的信号时,它会导致 Node.js 进程写入堆转储。 signal 必须是有效的信号名称。 默认禁用。

$ node --heapsnapshot-signal=SIGUSR2 index.js &
$ ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
node         1  5.5  6.1 787252 247004 ?       Ssl  16:43   0:02 node --heapsnapshot-signal=SIGUSR2 index.js
$ kill -USR2 1
$ ls
Heap.20190718.133405.15554.0.001.heapsnapshot

--heap-prof#

中英对照

稳定性: 1 - 实验

在启动时开始 V8 堆分析器,并在退出前将堆分析器写入磁盘。

如果未指定--heap-prof-dir,则生成的分析文件放在当前工作目录中。

如果未指定 --heap-prof-name,则生成的分析文件名为 Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile

$ node --heap-prof index.js
$ ls *.heapprofile
Heap.20190409.202950.15293.0.001.heapprofile

--heap-prof-dir#

中英对照

稳定性: 1 - 实验

指定 --heap-prof 生成的堆分析文件将被放置的目录。

默认值由 --diagnostic-dir 命令行选项控制。

--heap-prof-interval#

中英对照

稳定性: 1 - 实验

指定 --heap-prof 生成的堆分析文件的平均采样间隔(以字节为单位)。 默认为 512 * 1024 字节。

--heap-prof-name#

中英对照

稳定性: 1 - 实验

指定 --heap-prof 生成的堆分析文件的文件名。

--icu-data-dir=file#

中英对照

指定 ICU 数据加载路径。 (覆盖 NODE_ICU_DATA。)

--input-type=type#

中英对照

这将 Node.js 配置为将字符串输入解释为 CommonJS 或 ES 模块。 字符串输入是通过 --eval--printSTDIN 输入的。

有效值为 "commonjs""module"。 默认为 "commonjs"

REPL 不支持此选项。

--inspect-brk[=[host:]port]#

中英对照

host:port 上激活检查器并在用户脚本开始时中断。 默认 host:port127.0.0.1:9229

--inspect-port=[host:]port#

中英对照

设置检查器激活时使用的 host:port。 在通过发送 SIGUSR1 信号激活检查器时很有用。

默认主机是 127.0.0.1

请参阅下面有关 host 参数用法的安全警告

--inspect[=[host:]port]#

中英对照

host:port 上激活检查器。 默认为 127.0.0.1:9229

V8 检查器集成允许 Chrome 开发者工具和 IDE 等工具调试和分析 Node.js 实例。 该工具通过 tcp 端口连接到 Node.js 实例,并使用 Chrome 开发者工具协议进行通信。

注意:绑定检查器到公共的“IP:端口”组合是不安全的#

中英对照

将检查器绑定到具有开放端口的公共 IP(包括 0.0.0.0)是不安全的,因为它允许外部主机连接到检查器并执行远程代码执行攻击。

如果指定主机,请确保:

  • 无法从公共网络访问该主机。
  • 防火墙不允许端口上不需要的连接。 更具体地说,如果端口(默认情况下为 9229)不受防火墙保护,则 --inspect=0.0.0.0 是不安全的。

有关详细信息,请参阅调试安全隐患章节。

--inspect-publish-uid=stderr,http#

中英对照

指定检查器网络套接字网址的暴露方式。

默认情况下,检查器网络套接字网址在标准错误和 http://host:port/json/list 上的 /json/list 端点下可用。

--insecure-http-parser#

中英对照

使用接受无效 HTTP 标头的不安全 HTTP 解析器。 这可能允许与不一致的 HTTP 实现的互操作性。 它还可能允许请求走私和其他依赖于接受无效标头的 HTTP 攻击。 避免使用此选项。

--jitless#

中英对照

禁用可执行内存的运行时分配。 出于安全原因,某些平台可能需要这样做。 在其他平台上也可以减少攻击面,但性能影响可能比较严重。

此标志是从 V8 继承的,可能会在上游发生变化。 它可能会在非语义化主版本中消失。

--max-http-header-size=size#

中英对照

指定 HTTP 标头的最大大小(以字节为单位)。 默认为 16 KiB。

--napi-modules#

中英对照

此选项为空操作。 它是为了兼容性而保留的。

--no-addons#

中英对照

禁用 node-addons 导出条件以及禁用加载原生插件。 当指定 --no-addons 时,调用 process.dlopen 或加载原生 C++ 插件将失败并抛出异常。

--no-deprecation#

中英对照

静默弃用警告。

--no-force-async-hooks-checks#

中英对照

禁用 async_hooks 的运行时检查。 当启用 async_hooks 时,这些仍然会动态启用。

--no-global-search-paths#

中英对照

不从全局路径(如 $HOME/.node_modules$NODE_PATH)中搜索模块。

--no-warnings#

中英对照

静默所有进程警告(包括弃用的)。

--node-memory-debug#

中英对照

为 Node.js 内部的内存泄漏启用额外的调试检查。 这通常只用于开发者调试 Node.js 本身。

--openssl-config=file#

中英对照

在启动时加载 OpenSSL 配置文件。 除其他用途外,如果 Node.js 是针对支持 FIPS 的 OpenSSL 构建的,则可用于启用符合 FIPS 的加密。

--openssl-shared-config#

中英对照

启用 OpenSSL 默认配置部分,从 OpenSSL 配置文件中读取 openssl_conf。 默认配置文件名为 openssl.cnf,但可以使用环境变量 OPENSSL_CONF 或使用命令行选项 --openssl-config 进行更改。 默认 OpenSSL 配置文件的位置取决于 OpenSSL 如何链接到 Node.js。 共享 OpenSSL 配置可能会产生不必要的影响,建议使用特定于 Node.js 的配置部分,它是 nodejs_conf,并且在不使用此选项时是默认设置。

--openssl-legacy-provider#

中英对照

在动态链接到 OpenSSL 3.x 时启用 OpenSSL 3.0 旧版提供程序。有关更多信息,请参阅 OSSL_PROVIDER-legacy

--pending-deprecation#

中英对照

触发挂起的弃用警告。

挂起的弃用通常与运行时弃用相同,但值得注意的是,它们默认关闭关闭,除非设置了 --pending-deprecation 命令行标志或 NODE_PENDING_DEPRECATION=1 环境变量,否则不会触发。 待弃用用于提供一种选择性的"早期警告"机制,开发者可以利用该机制来检测弃用的 API 的使用情况。

--policy-integrity=sri#

中英对照

稳定性: 1 - 实验

如果策略不具有指定的完整性,则指示 Node.js 在运行任何代码之前出错。 它需要子资源完整性字符串作为参数。

--preserve-symlinks#

中英对照

指示模块加载器在解析和缓存模块时保留符号链接。

默认情况下,当 Node.js 从符号链接到不同磁盘位置的路径加载模块时,Node.js 将取消引用该链接并使用模块的实际磁盘“真实路径”作为既是标识符又是定位其他依赖模块的根路径。 在大多数情况下,这种默认行为是可以接受的。 但是,当使用符号链接的对等依赖项时,如下例所示,如果 moduleA 尝试要求 moduleB 作为对等依赖项,则默认行为会引发异常:

{appDir}
 ├── app
 │   ├── index.js
 │   └── node_modules
 │       ├── moduleA -> {appDir}/moduleA
 │       └── moduleB
 │           ├── index.js
 │           └── package.json
 └── moduleA
     ├── index.js
     └── package.json

--preserve-symlinks 命令行标志指示 Node.js 使用模块的符号链接路径而不是实际路径,从而允许找到符号链接的对等依赖项。

但是请注意,使用 --preserve-symlinks 会产生其他副作用。 具体来说,如果这些模块是从依赖树中的多个位置链接的,那么符号链接的原生模块可能无法加载(Node.js 会将它们视为两个单独的模块,并会尝试多次加载该模块,从而导致异常被抛出)。

--preserve-symlinks 标志不适用于允许 node --preserve-symlinks node_module/.bin/<foo> 工作的主模块。 要对主模块应用相同的行为,也请使用 --preserve-symlinks-main

--preserve-symlinks-main#

中英对照

指示模块加载器在解析和缓存主模块 (require.main) 时保留符号链接。

此标志的存在是为了让主模块可以选择加入 --preserve-symlinks 为所有其他导入提供的相同行为;但是,它们是单独的标志,以便与旧的 Node.js 版本向后兼容。

--preserve-symlinks-main 并不意味着 --preserve-symlinks;当在解析相对路径之前不希望遵循符号链接时,除了 --preserve-symlinks 之外,还使用 ​​--preserve-symlinks-main

有关详细信息,请参阅 --preserve-symlinks

--prof#

中英对照

生成 V8 分析器输出。

--prof-process#

中英对照

处理使用 V8 选项 --prof 生成的 V8 分析器输出。

--redirect-warnings=file#

中英对照

将进程警告写入给定文件而不是打印到标准错误。 如果文件不存在则创建,如果存在则追加。 如果在尝试将警告写入文件时发生错误,则警告将改为写入标准错误。

file 名称可以是绝对路径。 如果不是,则它将被写入的默认目录由 --diagnostic-dir 命令行选项控制。

--report-compact#

中英对照

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

--report-dir=directory, report-directory=directory#

中英对照

生成报告的位置。

--report-filename=filename#

中英对照

将写入报告的文件的名称。

如果文件名设置为 'stdout''stderr',则报告分别写入进程的 stdout 或 stderr。

--report-on-fatalerror#

中英对照

使报告能够在导致应用程序终止的致命错误(Node.js 运行时中的内部错误,例如内存不足)时触发。 用于检查各种诊断数据元素,例如堆、堆栈、事件循环状态、资源消耗等 推断致命错误。

--report-on-signal#

中英对照

在接收到正在运行的 Node.js 进程的指定(或预定义)信号时生成报告。 触发报告的信号通过 --report-signal 指定。

--report-signal=signal#

中英对照

设置或重置报告生成信号(Windows 不支持)。 默认信号为 SIGUSR2

--report-uncaught-exception#

中英对照

允许在进程由于未捕获的异常而退出时生成报告。 在结合原生堆栈和其他运行时环境数据检查 JavaScript 堆栈时很有用。

--secure-heap=n#

中英对照

初始化 n 个字节的 OpenSSL 安全堆。 当初始化时,安全堆用于密钥生成和其他操作期间 OpenSSL 中选定类型的分配。 这很有用,例如,防止敏感信息因指针溢出或不足而泄漏。

安全堆的大小是固定的,不能在运行时调整大小,因此,如果使用,选择足够大的堆来覆盖所有应用程序使用是很重要的。

给定的堆大小必须是 2 的幂。 任何小于 2 的值都将禁用安全堆。

默认情况下禁用安全堆。

安全堆在 Windows 上不可用。

有关详细信息,请参阅 CRYPTO_secure_malloc_init

--secure-heap-min=n#

中英对照

当使用 --secure-heap 时,--secure-heap-min 标志指定安全堆的最小分配。 最小值为 2。 最大值是 --secure-heap2147483647 中的较小者。 给定的值必须是 2 的幂。

--test#

中英对照

启动 Node.js 命令行测试运行器。 此标志不能与 --check--eval--interactive 或检查器组合。 请参阅从命令行运行测试了解更多详细信息。

--test-only#

中英对照

将测试运行器配置为仅执行设置了 only 选项的顶层测试。

--throw-deprecation#

中英对照

为弃用抛出错误。

--title=title#

中英对照

在启动时设置 process.title

--tls-cipher-list=list#

中英对照

指定替代的默认 TLS 密码列表。 需要使用加密支持构建 Node.js(默认)。

--tls-keylog=file#

中英对照

将 TLS 密钥材料记录到文件中。 密钥材料为 NSS SSLKEYLOGFILE 格式,可被软件(如 Wireshark)用于解密 TLS 流量。

--tls-max-v1.2#

中英对照

tls.DEFAULT_MAX_VERSION 设置为 'TLSv1.2'。 用于禁用对 TLSv1.3 的支持。

--tls-max-v1.3#

中英对照

将默认的 tls.DEFAULT_MAX_VERSION 设置为 'TLSv1.3'。 用于启用对 TLSv1.3 的支持。

--tls-min-v1.0#

中英对照

将默认的 tls.DEFAULT_MIN_VERSION 设置为 'TLSv1'。 用于与旧的 TLS 客户端或服务器兼容。

--tls-min-v1.1#

中英对照

将默认的 tls.DEFAULT_MIN_VERSION 设置为 'TLSv1.1'。 用于与旧的 TLS 客户端或服务器兼容。

--tls-min-v1.2#

中英对照

将默认的 tls.DEFAULT_MIN_VERSION 设置为 'TLSv1.2'。 这是 12.x 及更高版本的默认设置,但支持该选项是为了与较旧的 Node.js 版本兼容。

--tls-min-v1.3#

中英对照

将默认的 tls.DEFAULT_MIN_VERSION 设置为 'TLSv1.3'。 用于禁用对 TLSv1.2 的支持,它不如 TLSv1.3 安全。

--trace-atomics-wait#

中英对照

稳定性: 0 - 弃用

Atomics.wait() 调用的简短摘要打印到标准错误。 输出可能如下所示:

(node:15701) [Thread 0] Atomics.wait(&lt;address> + 0, 1, inf) started
(node:15701) [Thread 0] Atomics.wait(&lt;address> + 0, 1, inf) did not wait because the values mismatched
(node:15701) [Thread 0] Atomics.wait(&lt;address> + 0, 0, 10) started
(node:15701) [Thread 0] Atomics.wait(&lt;address> + 0, 0, 10) timed out
(node:15701) [Thread 0] Atomics.wait(&lt;address> + 4, 0, inf) started
(node:15701) [Thread 1] Atomics.wait(&lt;address> + 4, -1, inf) started
(node:15701) [Thread 0] Atomics.wait(&lt;address> + 4, 0, inf) was woken up by another thread
(node:15701) [Thread 1] Atomics.wait(&lt;address> + 4, -1, inf) was woken up by another thread

这里的字段对应于:

  • worker_threads.threadId 给定的线程标识
  • 有问题的 SharedArrayBuffer 的基地址,以及传给 Atomics.wait() 的索引对应的字节偏移量
  • 传给 Atomics.wait() 的期望值
  • 传给 Atomics.wait 的超时

--trace-deprecation#

中英对照

打印弃用的堆栈跟踪。

--trace-event-categories#

中英对照

使用 --trace-events-enabled 启用跟踪事件跟踪时应跟踪的逗号分隔的类别列表。

--trace-event-file-pattern#

中英对照

指定跟踪事件数据文件路径的模板字符串,它支持 ${rotation}${pid}

--trace-events-enabled#

中英对照

启用跟踪事件跟踪信息的收集。

--trace-exit#

中英对照

每当主动退出环境时打印堆栈跟踪,即调用 process.exit()

--trace-sigint#

中英对照

在 SIGINT 上打印堆栈跟踪。

--trace-sync-io#

中英对照

在第一轮事件循环后检测到同步 I/O 时打印堆栈跟踪。

--trace-tls#

中英对照

将 TLS 数据包跟踪信息打印到 stderr。 这可用于调试 TLS 连接问题。

--trace-uncaught#

中英对照

打印未捕获异常的堆栈跟踪;通常,打印与创建 Error 相关的堆栈跟踪,而这使得 Node.js 也打印与抛出值相关的堆栈跟踪(不需要是 Error 实例)

启用此选项可能会对垃圾回收行为产生负面影响。

--trace-warnings#

中英对照

打印进程警告的堆栈跟踪(包括弃用)。

--track-heap-objects#

中英对照

跟踪堆快照的堆对象分配。

--unhandled-rejections=mode#

中英对照

使用此标志可以改变发生未经处理的拒绝时应该发生的事情。 可以选择以下模式之一

  • throw: 触发 unhandledRejection。 如果未设置此钩子,则将未处理的拒绝上升为未捕获的异常。 这是默认值。
  • strict: 上升未处理的拒绝作为未捕获的异常。 如果处理了异常,则触发 unhandledRejection
  • warn: 始终触发警告,无论是否设置了 unhandledRejection 钩子,但不打印弃用警告。
  • warn-with-error-code: 触发 unhandledRejection。 如果未设置此钩子,则触发警告,并将进程退出码设置为 1。
  • none: 静默所有警告。

如果在命令行入口点的 ES 模块静态加载阶段发生拒绝,则它将始终将其作为未捕获的异常引发。

--use-bundled-ca, --use-openssl-ca#

中英对照

使用当前 Node.js 版本提供的捆绑 Mozilla CA 存储或使用 OpenSSL 的默认 CA 存储。 在构建时可以选择默认存储。

Node.js 提供的捆绑 CA 存储是 Mozilla CA 存储的快照,在发布时已修复。 它在所有支持的平台上都是相同的。

使用 OpenSSL 存储允许对存储进行外部修改。 对于大多数 Linux 和 BSD 发行版,这个存储是由发行版维护者和系统管理员维护的。 OpenSSL CA 存储位置取决于 OpenSSL 库的配置,但这可以在运行时使用环境变量进行更改。

参见 SSL_CERT_DIRSSL_CERT_FILE

--use-largepages=mode#

中英对照

在启动时将 Node.js 静态代码重新映射到大内存页面。 如果目标系统支持,则将导致 Node.js 静态代码移动到 2 MiB 页而不是 4 KiB 页。

以下值对 mode 有效:

  • off: 不会尝试映射。 这是默认值。
  • on: 如果操作系统支持,则将尝试映射。 映射失败将被忽略,并且将向标准错误打印消息。
  • silent: 如果操作系统支持,则将尝试映射。 映射失败将被忽略,并且不会被报告。

--v8-options#

中英对照

打印 V8 命令行选项。

--v8-pool-size=num#

中英对照

设置 V8 的线程池大小,用于分配后台作业。

如果设置为 0,则 V8 将根据在线处理器的数量选择合适大小的线程池。

如果提供的值大于 V8 的最大值,则选择最大值。

--watch#

中英对照

稳定性: 1 - 实验

以监视模式启动 Node.js。 在监视模式下,监视文件中的更改会导致 Node.js 进程重新启动。 默认情况下,监视模式将监视入口点和任何必需或导入的模块。 使用 --watch-path 指定要监视的路径。

此标志不能与 --check--eval--interactive 或 REPL 组合。

$ node --watch index.js

--watch-path#

中英对照

稳定性: 1 - 实验

以监视模式启动 Node.js 并指定要监视的路径。 在监视模式下,监视路径的更改会导致 Node.js 进程重新启动。 这将关闭对所需或导入模块的监视,即使与 --watch 结合使用也是如此。

此标志不能与 --check--eval--interactive 或 REPL 组合。

$ node --watch-path=./src --watch-path=./tests index.js

此选项仅在 macOS 和 Windows 上受支持。 当在不支持它的平台上使用该选项时,将抛出 ERR_FEATURE_UNAVAILABLE_ON_PLATFORM 异常。

--zero-fill-buffers#

中英对照

自动零填充所有新分配的 BufferSlowBuffer 实例。

-c, --check#

中英对照

语法检查脚本而不执行。

-e, --eval "script"#

中英对照

将以下参数作为 JavaScript 评估。 交互式解释器中预定义的模块也可以在 script 中使用。

在 Windows 上,使用 cmd.exe 单引号将无法正常工作,因为它只能识别双 " 进行引用。 在 Powershell 或 Git bash 中,'" 都可用。

-h, --help#

中英对照

打印 node 命令行选项。 此选项的输出不如本文档详细。

-i, --interactive#

中英对照

即使标准输入似乎不是终端,也会打开交互式解释器。

-p, --print "script"#

中英对照

-e 相同,但打印结果。

-r, --require module#

中英对照

在启动时预加载指定的模块。

遵循 require() 的模块解析规则。 module 可以是文件路径,也可以是 node 模块名称。

仅支持 CommonJS 模块。 尝试使用 --require 预加载 ES6 模块,则将失败并显示错误。

-v, --version#

中英对照

打印 node 的版本。

环境变量#

FORCE_COLOR=[1, 2, 3]#

中英对照

FORCE_COLOR 环境变量用于启用 ANSI 彩色输出。 值可能是:

  • 1true、或空字符串 '' 表示支持 16 色,
  • 2 表示支持 256 色,或
  • 3 表示支持 1600 万色。

当使用 FORCE_COLOR 并设置为支持的值时,NO_COLORNODE_DISABLE_COLORS 环境变量都将被忽略。

任何其他值都会导致彩色输出被禁用。

NODE_DEBUG=module[,…]#

中英对照

',' 分隔的应该打印调试信息的核心模块的列表。

NODE_DEBUG_NATIVE=module[,…]#

中英对照

',' 分隔的应打印调试信息的核心 C++ 模块的列表。

NODE_DISABLE_COLORS=1#

中英对照

当设置时,颜色将不会在交互式解释器中使用。

NODE_EXTRA_CA_CERTS=file#

中英对照

当设置时,众所周知的 "root" CA(如 VeriSign)将使用 file 中的额外证书进行扩展。 该文件应包含一个或多个 PEM 格式的可信证书。 如果文件丢失或格式不正确,则将使用 process.emitWarning() 触发消息消息(一次),否则将忽略任何错误。

当为 TLS 或 HTTPS 客户端或服务器显式指定 ca 选项属性时,则既不会使用众所周知的证书,也不会使用额外的证书。

node 作为 setuid root 运行或设置了 Linux 文件功能时,则将忽略此环境变量。

NODE_EXTRA_CA_CERTS 环境变量仅在 Node.js 进程第一次启动时读取。 在运行时使用 process.env.NODE_EXTRA_CA_CERTS 更改值对当前进程没有影响。

NODE_ICU_DATA=file#

中英对照

ICU (Intl 对象) 数据的数据路径。 在使用 small-icu 支持编译时将扩展链接数据。

NODE_NO_WARNINGS=1#

中英对照

当设置为 1 时,则静默进程警告。

NODE_OPTIONS=options...#

中英对照

以空格分隔的命令行选项列表 options... 在命令行选项之前被解释,因此命令行选项将在 options... 中的任何内容之后覆盖或复合。如果使用了环境中不允许的选项,例如 -p 或脚本文件。

如果选项值包含空格,则可以使用双引号转义:

NODE_OPTIONS='--require "./my path/file.js"'

作为命令行选项传入的单例标志将覆盖传给 NODE_OPTIONS 的相同标志:

# 检查器将在端口 5555 上可用
NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555

可以多次传入的标志将被视为首先传入其 NODE_OPTIONS 实例,然后是其命令行实例:

NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
# 相当于:
node --require "./a.js" --require "./b.js"

允许的 Node.js 选项是:

  • --conditions-C
  • --diagnostic-dir
  • --disable-proto
  • --dns-result-order
  • --enable-fips
  • --enable-source-maps
  • --experimental-abortcontroller
  • --experimental-fetch
  • --experimental-global-customevent
  • --experimental-global-webcrypto
  • --experimental-import-meta-resolve
  • --experimental-json-modules
  • --experimental-loader
  • --experimental-modules
  • --experimental-network-imports
  • --experimental-policy
  • --experimental-specifier-resolution
  • --experimental-top-level-await
  • --experimental-vm-modules
  • --experimental-wasi-unstable-preview1
  • --experimental-wasm-modules
  • --force-context-aware
  • --force-fips
  • --force-node-api-uncaught-exceptions-policy
  • --frozen-intrinsics
  • --heapsnapshot-near-heap-limit
  • --heapsnapshot-signal
  • --http-parser
  • --icu-data-dir
  • --input-type
  • --insecure-http-parser
  • --inspect-brk
  • --inspect-port--debug-port
  • --inspect-publish-uid
  • --inspect
  • --max-http-header-size
  • --napi-modules
  • --no-addons
  • --no-deprecation
  • --no-experimental-repl-await
  • --no-force-async-hooks-checks
  • --no-global-search-paths
  • --no-warnings
  • --node-memory-debug
  • --openssl-config
  • --openssl-legacy-provider
  • --openssl-shared-config
  • --pending-deprecation
  • --policy-integrity
  • --preserve-symlinks-main
  • --preserve-symlinks
  • --prof-process
  • --redirect-warnings
  • --report-compact
  • --report-dir--report-directory
  • --report-filename
  • --report-on-fatalerror
  • --report-on-signal
  • --report-signal
  • --report-uncaught-exception
  • --require-r
  • --secure-heap-min
  • --secure-heap
  • --test-only
  • --throw-deprecation
  • --title
  • --tls-cipher-list
  • --tls-keylog
  • --tls-max-v1.2
  • --tls-max-v1.3
  • --tls-min-v1.0
  • --tls-min-v1.1
  • --tls-min-v1.2
  • --tls-min-v1.3
  • --trace-atomics-wait
  • --trace-deprecation
  • --trace-event-categories
  • --trace-event-file-pattern
  • --trace-events-enabled
  • --trace-exit
  • --trace-sigint
  • --trace-sync-io
  • --trace-tls
  • --trace-uncaught
  • --trace-warnings
  • --track-heap-objects
  • --unhandled-rejections
  • --use-bundled-ca
  • --use-largepages
  • --use-openssl-ca
  • --v8-pool-size
  • --watch-path
  • --watch
  • --zero-fill-buffers

允许的 V8 选项是:

  • --abort-on-uncaught-exception
  • --disallow-code-generation-from-strings
  • --huge-max-old-generation-size
  • --interpreted-frames-native-stack
  • --jitless
  • --max-old-space-size
  • --perf-basic-prof-only-functions
  • --perf-basic-prof
  • --perf-prof-unwinding-info
  • --perf-prof
  • --stack-trace-limit

--perf-basic-prof-only-functions--perf-basic-prof--perf-prof-unwinding-info--perf-prof 仅在 Linux 上可用。

NODE_PATH=path[:…]#

中英对照

':' 分隔的目录列表,以模块搜索路径为前缀。

在 Windows 上,这是 ';' 分隔的列表。

NODE_PENDING_DEPRECATION=1#

中英对照

当设置为 1 时,触发挂起的弃用警告。

挂起的弃用通常与运行时弃用相同,但值得注意的是,它们默认关闭关闭,除非设置了 --pending-deprecation 命令行标志或 NODE_PENDING_DEPRECATION=1 环境变量,否则不会触发。 待弃用用于提供一种选择性的"早期警告"机制,开发者可以利用该机制来检测弃用的 API 的使用情况。

NODE_PENDING_PIPE_INSTANCES=instances#

中英对照

设置管道服务器等待连接时挂起的管道实例句柄数。 此设置仅适用于 Windows。

NODE_PRESERVE_SYMLINKS=1#

中英对照

当设置为 1 时,指示模块加载器在解析和缓存模块时保留符号链接。

NODE_REDIRECT_WARNINGS=file#

中英对照

当设置时,进程警告将触发到给定文件而不是打印到标准错误 如果文件不存在则创建,如果存在则追加。 如果在尝试将警告写入文件时发生错误,则警告将改为写入标准错误。 这相当于使用 --redirect-warnings=file 命令行标志。

NODE_REPL_HISTORY=file#

中英对照

用于存储持久的交互式解释器历史的文件路径。 默认路径是 ~/.node_repl_history,会被此变量覆盖。 将值设置为空字符串(''' ')会禁用持久的交互式解释器历史记录。

NODE_REPL_EXTERNAL_MODULE=file#

中英对照

Node.js 模块的路径,该模块将代替内置交互式解释器加载。 将此值覆盖为空字符串 ('') ,则将使用内置的交互式解释器。

NODE_SKIP_PLATFORM_CHECK=value#

中英对照

如果 value 等于 '1',则在 Node.js 启动期间跳过对支持平台的检查。 Node.js 可能无法正确地执行。 在不受支持的平台上遇到的任何问题都不会得到修复。

NODE_TLS_REJECT_UNAUTHORIZED=value#

中英对照

如果 value 等于 '0',则对 TLS 连接禁用证书验证。 这使得 TLS 和 HTTPS 不安全。 强烈建议不要使用此环境变量。

NODE_V8_COVERAGE=dir#

中英对照

当设置时,Node.js 将开始将 V8 JavaScript 代码覆盖源映射数据输出到作为参数提供的目录(覆盖信息以 JSON 格式写入带有 coverage 前缀的文件)。

NODE_V8_COVERAGE 将自动传播到子进程,从而更容易检测调用 child_process.spawn() 系列函数的应用程序。 NODE_V8_COVERAGE 可以设置为空字符串,防止传播。

覆盖范围的输出#

中英对照

覆盖输出为顶层键 result 上的 ScriptCoverage 对象数组:

{
  "result": [
    {
      "scriptId": "67",
      "url": "internal/tty.js",
      "functions": []
    }
  ]
}
源码映射的缓存#

中英对照

稳定性: 1 - 实验

如果找到,则源映射数据将附加到 JSON 覆盖对象上的顶层键 source-map-cache

source-map-cache 是一个对象,其中的键代表从中提取源映射的文件,其值包括原始源映射网址(在键 url 中)、解析的 Source Map v3 信息(在键 data 中)和行长度源文件(在键 lineLengths 中)。

{
  "result": [
    {
      "scriptId": "68",
      "url": "file:///absolute/path/to/source.js",
      "functions": []
    }
  ],
  "source-map-cache": {
    "file:///absolute/path/to/source.js": {
      "url": "./path-to-map.json",
      "data": {
        "version": 3,
        "sources": [
          "file:///absolute/path/to/original.js"
        ],
        "names": [
          "Foo",
          "console",
          "info"
        ],
        "mappings": "MAAMA,IACJC,YAAaC",
        "sourceRoot": "./"
      },
      "lineLengths": [
        13,
        62,
        38,
        27
      ]
    }
  }
}

NO_COLOR=<any>#

中英对照

NO_COLORNODE_DISABLE_COLORS 的别名。 环境变量的值是任意的。

OPENSSL_CONF=file#

中英对照

在启动时加载 OpenSSL 配置文件。 除其他用途外,如果 Node.js 是使用 ./configure --openssl-fips 构建的,则可用于启用符合 FIPS 的加密。

如果使用 --openssl-config 命令行选项,则环境变量将被忽略。

SSL_CERT_DIR=dir#

中英对照

如果启用了 --use-openssl-ca,则将覆盖并设置包含受信任证书的 OpenSSL 目录。

注意,除非显式设置子环境,否则任何子进程都会继承此环境变量,如果它们使用 OpenSSL,可能会导致它们信任与节点相同的 CA。

SSL_CERT_FILE=file#

中英对照

如果启用了 --use-openssl-ca,则将覆盖并设置包含受信任证书的 OpenSSL 文件。

注意,除非显式设置子环境,否则任何子进程都会继承此环境变量,如果它们使用 OpenSSL,可能会导致它们信任与节点相同的 CA。

TZ#

中英对照

TZ 环境变量用于指定时区配置。

虽然 Node.js 不支持所有各种 TZ 在其他环境中的处理方式,但它确实支持基本的时区 ID(例如 'Etc/UTC''Europe/Paris'、或 'America/New_York')。 它可能支持其他一些缩写或别名,但强烈建议不要使用这些缩写或别名,并且不能保证。

$ TZ=Europe/Dublin node -pe "new Date().toString()"
Wed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time)

UV_THREADPOOL_SIZE=size#

中英对照

将 libuv 的线程池中使用的线程数设置为 size 个线程。

Node.js 尽可能使用异步的系统 API,但在它们不存在的情况下,libuv 的线程池用于基于同步的系统 API 创建异步的 node API。 使用线程池的 Node.js API 有:

  • 所有 fs API,除了文件监视器 API 和那些显式同步的
  • 异步加密 API,例如 crypto.pbkdf2()crypto.scrypt()crypto.randomBytes()crypto.randomFill()crypto.generateKeyPair()
  • dns.lookup()
  • 所有 zlib API,除了那些显式同步的

因为 libuv 的线程池有固定的大小,这意味着如果这些 API 中的任何一个由于某种原因需要很长时间,则在 libuv 的线程池中运行的其他(看似无关的)API 的性能将会下降。 为了缓解此问题,潜在的解决方案是通过将 'UV_THREADPOOL_SIZE' 环境变量设置为大于 4(其当前默认值)的值来增加 libuv 线程池的大小。 有关更多信息,请参阅 libuv 线程池文档

有用的 V8 选项#

中英对照

V8 有自己的一组命令行选项。 任何提供给 node 的 V8 命令行选项都将传给 V8 来处理。 V8 的选项没有稳定性保证。 V8 团队本身并不认为它们是其正式 API 的一部分,并保留随时更改它们的权利。 同样,它们也不在 Node.js 稳定性保证范围内。 许多 V8 选项只对 V8 开发者有用。 尽管如此,有一小组 V8 选项广泛适用于 Node.js,它们记录在此处:

--max-old-space-size=SIZE#

中英对照

设置 V8 旧内存部分的最大内存大小。 随着内存消耗接近极限,V8 会花更多的时间在垃圾回收上,以释放未使用的内存。

在具有 2 GiB 内存的机器上,考虑将其设置为 1536 (1.5 GiB) 以留出一些内存用于其他用途并避免交换。

$ node --max-old-space-size=1536 index.js

--max-semi-space-size=SIZE(以兆字节为单位)#

中英对照

为 V8 的清除垃圾收集器设置最大的半空间大小,以 MiB(兆字节)为单位。 增加半空间的最大尺寸可能会提高 Node.js 的吞吐量,但会消耗更多内存。

由于 V8 堆的年轻代大小是半空间大小的三倍(参见 V8 中的 YoungGenerationSizeFromSemiSpaceSize),因此半空间增加 1 MiB 适用于三个单独的半空间中的每一个,并导致堆大小增加 3 MiB。 吞吐量的提高取决于您的工作负荷(参见 #42511)。

64 位系统的默认值为 16 MiB,32 位系统的默认值为 8 MiB。 要为您的应用程序获得最佳配置,您应该在为您的应用程序运行基准测试时尝试不同的 max-semi-space-size 值。

例如,在 64 位系统上进行基准测试:

for MiB in 16 32 64 128; do
    node --max-semi-space-size=$MiB index.js
done
返回顶部