Node.js v18.18.2 文档

概要#

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

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

node --v8-options

不带参数执行以启动REPL 交互式编程环境。

有关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 环境变量传递的选项。

-#

标准输入的别名。类似于在其他命令行实用程序中使用- ，这意味着从 stdin 读取脚本，并将其余选项传递给该脚本。

--#

指示节点选项的结尾。将其余参数传递给脚本。如果在此之前没有提供脚本文件名或 eval/print 脚本，则下一个参数将用作脚本文件名。

--abort-on-uncaught-exception#

中止而不是退出会导致生成核心文件，以便使用调试器（例如lldb、gdb和mdb）进行事后分析。

如果传递此标志，则仍然可以通过process.setUncaughtExceptionCaptureCallback()（以及通过使用 使用它的node:domain模块）将行为设置为不中止 。

--build-snapshot#

当进程退出时生成快照 blob 并将其写入磁盘，稍后可以使用--snapshot-blob加载。

构建快照时，如果未指定--snapshot-blob，则生成的 blob 将默认写入 当前工作目录中的snapshot.blob 。否则它将被写入--snapshot-blob指定的路径。

$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js

# Run snapshot.js to initialize the application and snapshot the
# state of it into snapshot.blob.
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

$ echo "console.log(globalThis.foo)" > index.js

# Load the generated snapshot and start the application from index.js.
$ node --snapshot-blob snapshot.blob index.js
I am from the snapshot copy

v8.startupSnapshot API可用于在快照构建时指定入口点，从而避免在反序列化时需要额外的入口脚本：

$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js
$ node --snapshot-blob snapshot.blob
I am from the snapshot copy

有关更多信息，请查看v8.startupSnapshot API文档。

目前对运行时快照的支持是实验性的，因为：

1. 快照尚不支持用户态模块，因此只能对一个文件进行快照。不过，在构建快照之前，用户可以使用自己选择的捆绑器将应用程序捆绑到单个脚本中。
2. 尽管 Node.js 核心测试套件会检查是否可以对一些相当复杂的应用程序进行快照，但只有一部分内置模块可以在快照中工作。正在添加对更多模块的支持。如果构建快照时发生任何崩溃或错误行为，请在Node.js 问题跟踪器中提交报告，并在用户空间快照的跟踪问题中链接到该 报告。

--completion-bash#

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

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

-C condition , --conditions=condition#

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

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

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

例如，要运行具有“开发”分辨率的模块：

$ node -C development app.js copy

--cpu-prof#

在启动时启动 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 copy

--cpu-prof-dir#

指定由--cpu-prof生成的 CPU 配置文件将放置的目录。

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

--cpu-prof-interval#

指定--cpu-prof生成的 CPU 配置文件的采样间隔（以微秒为单位）。默认值为 1000 微秒。

--cpu-prof-name#

指定--cpu-prof生成的 CPU 配置文件的文件名。

--diagnostic-dir=directory#

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

影响默认输出目录：

• --cpu-prof-dir
• --heap-prof-dir
• --redirect-warnings

--disable-proto=mode#

禁用Object.prototype.__proto__属性。如果mode为delete，则该属性将被完全删除。如果mode为throw，则访问该属性会引发异常，代码为ERR_PROTO_ACCESS。

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

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

--dns-result-order=order#

在dns.lookup()和 dnsPromises.lookup()中设置verbatim的默认值。该值可以是：

• ipv4first：设置默认值verbatim false。
• verbatim：设置默认值verbatim true。

默认值为verbatim且dns.setDefaultResultOrder() 的优先级高于--dns-result-order。

--enable-fips#

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

--enable-network-family-autoselection#

启用族自动选择算法，除非连接选项明确禁用它。

--enable-source-maps#

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

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

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

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

--experimental-global-customevent#

在全局范围内公开CustomEvent Web API 。

--experimental-global-webcrypto#

在全局范围内公开Web Crypto API 。

--experimental-import-meta-resolve#

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

--experimental-loader=module#

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

--experimental-network-imports#

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

--experimental-policy#

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

--no-experimental-fetch#

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

--no-experimental-repl-await#

使用此标志禁用 REPL 中的顶级等待。

--experimental-shadow-realm#

使用此标志启用ShadowRealm支持。

--experimental-specifier-resolution=mode#

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

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

有关示例用法，请参阅自定义 ESM 说明符解析。

--experimental-test-coverage#

当与node:test模块结合使用时，代码覆盖率报告将作为测试运行器输出的一部分生成。如果没有运行测试，则不会生成覆盖率报告。有关更多详细信息，请参阅有关从测试中收集代码覆盖率的文档 。

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

启用实验性冻结内在函数，例如Array和Object。

仅支持根上下文。无法保证 globalThis.Array确实是默认的内部引用。在此标志下代码可能会崩溃。

为了允许添加 Polyfill， --require和--import都在冻结内在函数之前运行。

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

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

为了防止现有附加组件使进程崩溃，默认情况下不启用此标志。将来，该标志将默认启用以强制执行正确的行为。

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

当 V8 堆使用率接近堆限制时，将 V8 堆快照写入磁盘。count应该是一个非负整数（在这种情况下，Node.js 将不超过max_count个快照写入磁盘）。

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

生成 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
.... copy

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

--heap-prof#

在启动时启动 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 copy

--heap-prof-dir#

指定由--heap-prof生成的堆配置文件将放置的目录。

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

--heap-prof-interval#

指定--heap-prof生成的堆配置文件的平均采样间隔（以字节为单位）。默认为 512 * 1024 字节。

--heap-prof-name#

指定由--heap-prof生成的堆配置文件的文件名。

--icu-data-dir=file#

指定 ICU 数据加载路径。（覆盖NODE_ICU_DATA。）

--import=module#

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

遵循ECMAScript 模块解析规则。使用--require加载CommonJS 模块。预加载--require的模块将在预加载--import的模块之前运行。

--input-type=type#

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

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

REPL 不支持此选项。

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

在host:port上激活检查器并在用户脚本开始处中断。默认host:port是127.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 DevTools 和 IDE 等工具来调试和分析 Node.js 实例。这些工具通过 TCP 端口连接到 Node.js 实例，并使用Chrome DevTools Protocol进行通信。

警告：将检查器绑定到公共 IP:端口组合是不安全的#

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

如果指定主机，请确保：

• 无法从公共网络访问该主机。
• 防火墙禁止端口上不需要的连接。

更具体地说，如果端口（默认为9229 ）不受防火墙保护，则 --inspect=0.0.0.0不安全。

有关详细信息，请参阅调试安全影响部分。

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

指定检查器 Web 套接字 url 暴露的方式。

默认情况下，检查器 websocket url 在 stderr 和/json/list上的/json/list 端点下可用。

--insecure-http-parser#

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

--jitless#

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

该标志继承自 V8，并且可能会在上游发生变化。它可能会在非 semver 主要版本中消失。

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

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

--napi-modules#

该选项是无操作的。保留它是为了兼容性。

--no-addons#

禁用node-addons导出条件并禁用加载本机插件。当指定--no-addons时，调用process.dlopen或需要本机 C++ 插件将失败并引发异常。

--no-deprecation#

静默弃用警告。

--no-extra-info-on-fatal-exception#

隐藏有关导致退出的致命异常的额外信息。

--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_conf从 OpenSSL 配置文件中读取。默认配置文件名为 openssl.cnf，但可以使用环境变量 OPENSSL_CONF或使用命令行选项--openssl-config进行更改。默认 OpenSSL 配置文件的位置取决于 OpenSSL 链接到 Node.js 的方式。共享 OpenSSL 配置可能会产生不必要的影响，建议使用特定于 Node.js 的配置部分，即 nodejs_conf，并且在不使用此选项时为默认配置。

--openssl-legacy-provider#

启用 OpenSSL 3.0 旧版提供程序。有关更多信息，请参阅 OSSL_PROVIDER-legacy。

--pending-deprecation#

发出待处理的弃用警告。

待处理的弃用通常与运行时弃用相同，但值得注意的例外是它们默认情况下处于关闭状态，并且除非使用 --pending-deprecation命令行标志或 NODE_PENDING_DEPRECATION=1环境，否则不会发出变量，已设置。待弃用用于提供一种选择性“预警”机制，开发人员可以利用该机制来检测已弃用的 API 使用情况。

--policy-integrity=sri#

如果策略不具有指定的完整性，则指示 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 copy

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

将进程警告写入给定文件，而不是打印到 stderr。如果该文件不存在，则创建该文件；如果存在，则将其附加到该文件。如果尝试将警告写入文件时发生错误，警告将改为写入 stderr。

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-heap或2147483647中的较小者。给定的值必须是 2 的幂。

--snapshot-blob=path#

与--build-snapshot一起使用时，--snapshot-blob指定写入生成的快照 blob 的路径。如果未指定，生成的 blob 将写入当前工作目录中的snapshot.blob 。

当不使用--build-snapshot时，--snapshot-blob指定用于恢复应用程序状态的 blob 的路径。

加载快照时，Node.js 会检查：

1. 正在运行的 Node.js 二进制文件的版本、架构和平台与生成快照的二进制文件完全相同。
2. V8 标志和 CPU 功能与生成快照的二进制文件兼容。

如果它们不匹配，Node.js 将拒绝加载快照并以状态代码 1 退出。

--test#

启动 Node.js 命令行测试运行程序。此标志不能与--watch-path、--check、--eval、--interactive或检查器结合使用 。 有关更多详细信息，请参阅有关从命令行运行测试的文档。

--test-name-pattern#

正则表达式，将测试运行器配置为仅执行名称与提供的模式匹配的测试。有关更多详细信息，请参阅有关按名称过滤测试的文档 。

--test-reporter#

运行测试时使用的测试报告器。有关更多详细信息，请参阅有关测试报告器的文档 。

--test-reporter-destination#

相应测试报告者的目的地。有关更多详细信息，请参阅有关测试报告器的文档 。

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

打印对 stderr 的Atomics.wait()调用的简短摘要。输出可能如下所示：

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

这里的字段对应于：

• 由worker_threads.threadId给出的线程 ID
• 相关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_DIR和SSL_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，则 Node.js 将根据并行量的估计选择适当的线程池大小。

并行度是指在给定机器上可以同时执行的计算数量。一般来说，它与 CPU 的数量相同，但在虚拟机或容器等环境中可能会有所不同。

--watch#

以监视模式启动 Node.js。当处于监视模式时，监视文件中的更改会导致 Node.js 进程重新启动。默认情况下，监视模式将监视入口点以及任何所需或导入的模块。使用--watch-path指定要观看的路径。

此标志不能与--check、--eval、--interactive或 REPL结合使用 。

$ node --watch index.js copy

--watch-path#

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

此标志不能与--check、--eval、--interactive、--test或 REPL结合使用 。

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

此选项仅在 macOS 和 Windows 上受支持。当在不支持该选项的平台上使用该选项时，将引发ERR_FEATURE_UNAVAILABLE_ON_PLATFORM异常。

--watch-preserve-output#

当监视模式重新启动进程时，禁用控制台的清除。

$ node --watch --watch-preserve-output test.js copy

--zero-fill-buffers#

自动对所有新分配的Buffer和SlowBuffer 实例进行零填充。

-c , --check#

对脚本进行语法检查而不执行。

-e , --eval "script"#

将以下参数评估为 JavaScript。REPL 中预定义的模块也可以在script中使用。

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

-h , --help#

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

-i , --interactive#

即使 stdin 看起来不是终端，也会打开 REPL。

-p , --print "script"#

与-e相同，但打印结果。

-r , --require module#

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

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

仅支持 CommonJS 模块。使用--import预加载ECMAScript 模块。预加载--require的模块将在预加载--import的模块之前运行。

-v , --version#

打印节点的版本。

环境变量#

FORCE_COLOR=[1, 2, 3]#

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

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

当使用FORCE_COLOR并将其设置为支持的值时， NO_COLOR和NODE_DISABLE_COLORS环境变量都将被忽略。

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

NODE_DEBUG=module[,…]#

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

NODE_DEBUG_NATIVE=module[,…]#

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

NODE_DISABLE_COLORS=1#

设置后，颜色将不会在 REPL 中使用。

NODE_EXTRA_CA_CERTS=file#

设置后，众所周知的“根”CA（如 VeriSign）将使用file中的额外证书进行扩展。该文件应包含一个或多个 PEM 格式的受信任证书。如果文件丢失或格式错误，将使用process.emitWarning()发出一条消息（一次） ，但任何错误都会被忽略。

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

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

仅当 Node.js 进程首次启动时才会读取NODE_EXTRA_CA_CERTS环境变量。使用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.js 将退出并出现错误。

如果选项值包含空格，可以使用双引号将其转义：

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

作为命令行选项传递的单例标志将覆盖传递到NODE_OPTIONS的相同标志：

# The inspector will be available on port 5555
NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555 copy

可以多次传递的标志将被视为首先传递其 NODE_OPTIONS实例，然后传递其命令行实例：

NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
# is equivalent to:
node --require "./a.js" --require "./b.js" copy

允许的 Node.js 选项有：

• --conditions , -C
• --diagnostic-dir
• --disable-proto
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --experimental-abortcontroller
• --experimental-global-customevent
• --experimental-global-webcrypto
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-network-imports
• --experimental-policy
• --experimental-shadow-realm
• --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
• --import
• --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-fetch
• --no-experimental-repl-await
• --no-extra-info-on-fatal-exception
• --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
• --snapshot-blob
• --test-only
• --test-reporter-destination
• --test-reporter
• --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-preserve-output
• --watch
• --zero-fill-buffers

允许的 V8 选项有：

• --abort-on-uncaught-exception
• --disallow-code-generation-from-strings
• --enable-etw-stack-walking
• --huge-max-old-generation-size
• --interpreted-frames-native-stack
• --jitless
• --max-old-space-size
• --max-semi-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 上可用。

--enable-etw-stack-walking仅适用于 Windows。

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#

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

NODE_REPL_HISTORY=file#

用于存储持久 REPL 历史记录的文件的路径。默认路径是 ~/.node_repl_history，它被此变量覆盖。将该值设置为空字符串（''或' '）会禁用持久 REPL 历史记录。

NODE_REPL_EXTERNAL_MODULE=file#

将加载以代替内置 REPL 的 Node.js 模块的路径。将此值覆盖为空字符串 ( '' ) 将使用内置 REPL。

NODE_SKIP_PLATFORM_CHECK=value#

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

NODE_TEST_CONTEXT=value#

如果value等于'child'，测试报告选项将被覆盖，测试输出将以 TAP 格式发送到 stdout。如果提供任何其他值，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": []
    }
  ]
} copy

源映射缓存#

如果找到，Source map数据将附加到JSON 覆盖对象上的顶级键source-map-cache 。

source-map-cache是一个对象，其键表示从中提取源映射的文件，值包括原始源映射 URL（在键url中）、解析的源映射 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
      ]
    }
  }
} copy

NO_COLOR=<any>#

NO_COLOR是NODE_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) copy

UV_THREADPOOL_SIZE=size#

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

Node.js 只要有可能就会使用异步系统 API，但在不存在异步系统 API 的情况下，libuv 的线程池用于基于同步系统 API 创建异步Node-API。使用线程池的 Node.js API 包括：

• 所有fs API，文件观察器 API 和显式同步的 API 除外
• 异步加密 API，例如crypto.pbkdf2()、crypto.scrypt()、 crypto.randomBytes()、crypto.randomFill()、crypto.generateKeyPair()
• dns.lookup()
• 所有zlib API，显式同步的 API 除外

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

有用的 V8 选项#

V8 有自己的一组 CLI 选项。提供给node的任何 V8 CLI 选项 都将传递给 V8 进行处理。V8的选项没有稳定性保证。V8 团队本身并不认为它们是其正式 API 的一部分，并保留随时更改它们的权利。同样，它们也不属于 Node.js 稳定性保证的范围。许多 V8 选项只有 V8 开发人员感兴趣。尽管如此，还是有一小组广泛适用于 Node.js 的 V8 选项，它们记录在此处：

--max-old-space-size=SIZE（以兆字节为单位）#

设置V8旧内存部分的最大内存大小。当内存消耗接近极限时，V8 将花费更多时间进行垃圾收集，以释放未使用的内存。

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

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

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