Node.js v21.7.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 模块加载器解析，或者如果传递了 --experimental-default-type=module，则由 ES 模块加载器 解析。如果未找到相应的文件，则会抛出错误。

如果找到文件，则其路径将在以下任何情况下传递给 ES 模块加载器

• 程序使用强制入口点使用 ECMAScript 模块加载器加载的命令行标志启动，例如 --import 或 --experimental-default-type=module。
• 该文件具有 .mjs 扩展名。
• 该文件没有 .cjs 扩展名，并且最近的父级 package.json 文件包含一个值为 "module" 的顶级 "type" 字段。

否则，将使用 CommonJS 模块加载器加载该文件。有关更多详细信息，请参见 模块加载器。

ECMAScript 模块加载器入口点注意事项#

在加载时，ES 模块加载器 加载程序入口点，node 命令将仅接受具有 .js、.mjs 或 .cjs 扩展名的文件作为输入；当启用 --experimental-wasm-modules 时，具有 .wasm 扩展名；当传递 --experimental-default-type=module 时，没有扩展名。

选项#

所有选项（包括 V8 选项）都允许使用连字符 (-) 或下划线 (_) 分隔单词。例如，--pending-deprecation 等效于 --pending_deprecation。

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

-#

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

--#

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

--abort-on-uncaught-exception#

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

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

--allow-addons#

使用 权限模型 时，进程默认情况下将无法使用本机插件。尝试这样做将抛出 ERR_DLOPEN_DISABLED，除非用户在启动 Node.js 时显式传递 --allow-addons 标志。

示例

// Attempt to require an native addon
require('nodejs-addon-example'); copy

$ node --experimental-permission --allow-fs-read=* index.js
node:internal/modules/cjs/loader:1319
  return process.dlopen(module, path.toNamespacedPath(filename));
                 ^

Error: Cannot load native addon because loading addons is disabled.
    at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12)
    at Module.require (node:internal/modules/cjs/loader:1115:19)
    at require (node:internal/modules/helpers:130:18)
    at Object.<anonymous> (/home/index.js:1:15)
    at Module._compile (node:internal/modules/cjs/loader:1233:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12) {
  code: 'ERR_DLOPEN_DISABLED'
} copy

--allow-child-process#

使用 权限模型 时，进程默认情况下将无法生成任何子进程。尝试这样做将抛出 ERR_ACCESS_DENIED，除非用户在启动 Node.js 时显式传递 --allow-child-process 标志。

示例

const childProcess = require('node:child_process');
// Attempt to bypass the permission
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']); copy

$ node --experimental-permission --allow-fs-read=* index.js
node:internal/child_process:388
  const err = this._handle.spawn(options);
                           ^
Error: Access to this API has been restricted
    at ChildProcess.spawn (node:internal/child_process:388:28)
    at Object.spawn (node:child_process:723:9)
    at Object.<anonymous> (/home/index.js:3:14)
    at Module._compile (node:internal/modules/cjs/loader:1120:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1174:10)
    at Module.load (node:internal/modules/cjs/loader:998:32)
    at Module._load (node:internal/modules/cjs/loader:839:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'ChildProcess'
} copy

--allow-fs-read#

此标志使用 权限模型 配置文件系统读取权限。

--allow-fs-read 标志的有效参数为

• * - 允许所有 FileSystemRead 操作。
• 可以使用多个 --allow-fs-read 标志来允许多个路径。例如 --allow-fs-read=/folder1/ --allow-fs-read=/folder1/

不再允许用逗号 (,) 分隔的路径。当传递带有逗号的单个标志时，将显示警告。

可以在 文件系统权限 文档中找到示例。

CLI 标志目前不支持相对路径。

初始化模块也需要被允许。请考虑以下示例

$ node --experimental-permission t.js
node:internal/modules/cjs/loader:162
  const result = internalModuleStat(filename);
                 ^

Error: Access to this API has been restricted
    at stat (node:internal/modules/cjs/loader:162:18)
    at Module._findPath (node:internal/modules/cjs/loader:640:16)
    at resolveMainPath (node:internal/modules/run_main:15:25)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:53:24)
    at node:internal/main/run_main_module:23:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'FileSystemRead',
  resource: '/Users/rafaelgss/repos/os/node/t.js'
} copy

该进程需要访问 index.js 模块

node --experimental-permission --allow-fs-read=/path/to/index.js index.js copy

--allow-fs-write#

此标志使用 权限模型 配置文件系统写入权限。

--allow-fs-write 标志的有效参数为

• * - 允许所有 FileSystemWrite 操作。
• 可以使用多个 --allow-fs-read 标志来允许多个路径。例如 --allow-fs-read=/folder1/ --allow-fs-read=/folder1/

不再允许用逗号 (,) 分隔的路径。当传递带有逗号的单个标志时，将显示警告。

可以在 文件系统权限 文档中找到示例。

CLI 标志不支持相对路径。

--allow-worker#

在使用 权限模型 时，进程默认情况下将无法创建任何工作线程。出于安全原因，除非用户在主 Node.js 进程中显式传递 --allow-worker 标志，否则调用将抛出 ERR_ACCESS_DENIED 错误。

示例

const { Worker } = require('node:worker_threads');
// Attempt to bypass the permission
new Worker(__filename); copy

$ node --experimental-permission --allow-fs-read=* index.js
node:internal/worker:188
    this[kHandle] = new WorkerImpl(url,
                    ^

Error: Access to this API has been restricted
    at new Worker (node:internal/worker:188:21)
    at Object.<anonymous> (/home/index.js.js:3:1)
    at Module._compile (node:internal/modules/cjs/loader:1120:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1174:10)
    at Module.load (node:internal/modules/cjs/loader:998:32)
    at Module._load (node:internal/modules/cjs/loader:839:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WorkerThreads'
} copy

--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 问题跟踪器 中提交报告，并在 用户空间快照跟踪问题 中链接到它。

--build-snapshot-config#

指定 JSON 配置文件的路径，该文件配置快照创建行为。

以下选项目前受支持

• builder <string> 必需。为在构建快照之前执行的脚本提供名称，就像使用 builder 作为主脚本名称传递了 --build-snapshot 一样。
• withoutCodeCache <boolean> 可选。包含代码缓存会减少在快照中编译函数所花费的时间，但会以更大的快照大小为代价，并可能破坏快照的可移植性。

使用此标志时，命令行上提供的其他脚本文件不会执行，而是被解释为常规命令行参数。

-c, --check#

在不执行的情况下检查脚本语法。

--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" 将始终按定义应用。

例如，要使用“development”解析运行模块

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-warning=code-or-type#

通过 code 或 type 禁用特定进程警告。

从 process.emitWarning() 发出的警告可能包含 code 和 type。此选项将不会发出具有匹配 code 或 type 的警告。

弃用警告的列表：弃用 API 列表

Node.js 核心警告类型：DeprecationWarning 和 ExperimentalWarning

例如，以下脚本在使用 node --disable-warning=DEP0025 执行时不会发出 DEP0025 require('node:sys')。

import sys from 'node:sys';const sys = require('node:sys');copy

例如，以下脚本将发出 DEP0025 require('node:sys')，但不会发出任何实验性警告（例如，在 <=v21 中的 ExperimentalWarning: vm.measureMemory is an experimental feature），当使用 node --disable-warning=ExperimentalWarning 执行时。

import sys from 'node:sys';
import vm from 'node:vm';

vm.measureMemory();const sys = require('node:sys');
const vm = require('node:vm');

vm.measureMemory();copy

--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 的加密。（需要 Node.js 针对符合 FIPS 的 OpenSSL 构建。）

--enable-network-family-autoselection#

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

--enable-source-maps#

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

当使用转译器（如 TypeScript）时，应用程序抛出的堆栈跟踪引用的是转译后的代码，而不是原始源位置。--enable-source-maps启用 Source Map 的缓存，并尽力根据原始源文件报告堆栈跟踪。

覆盖Error.prepareStackTrace可能会阻止--enable-source-maps修改堆栈跟踪。在覆盖函数中调用并返回原始Error.prepareStackTrace的结果，以使用源映射修改堆栈跟踪。

const originalPrepareStackTrace = Error.prepareStackTrace;
Error.prepareStackTrace = (error, trace) => {
  // Modify error and trace and format stack trace with
  // original Error.prepareStackTrace.
  return originalPrepareStackTrace(error, trace);
}; copy

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

--env-file=config#

从当前目录的相对路径加载环境变量文件，使它们可供process.env上的应用程序使用。配置 Node.js 的环境变量（例如NODE_OPTIONS）将被解析并应用。如果环境和文件中定义了相同的变量，则环境中的值优先。

可以传递多个--env-file参数。后续文件将覆盖先前文件中定义的现有变量。

node --env-file=.env --env-file=.development.env index.js copy

文件格式应为每行一个环境变量名称和值的键值对，用=分隔。

PORT=3000 copy

#后的任何文本都被视为注释。

# This is a comment
PORT=3000 # This is also a comment copy

值可以以以下引号开头和结尾：\、"或'。它们将从值中省略。

USERNAME="nodejs" # will result in `nodejs` as the value. copy

支持多行值。

MULTI_LINE="THIS IS
A MULTILINE"
# will result in `THIS IS\nA MULTILINE` as the value. copy

键之前的export关键字将被忽略。

export USERNAME="nodejs" # will result in `nodejs` as the value. copy

-e, --eval "script"#

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

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

--experimental-default-type=type#

定义以下要使用的模块系统，module或commonjs。

• 通过--eval或 STDIN 提供的字符串输入，如果--input-type未指定。

• 以.js结尾或没有扩展名的文件，如果同一文件夹或任何父文件夹中不存在package.json文件。

• 以.js结尾或没有扩展名的文件，如果最近的父package.json字段缺少"type"字段；除非package.json文件夹或任何父文件夹位于node_modules文件夹内。

换句话说，--experimental-default-type=module 将所有 Node.js 当前默认使用 CommonJS 的地方改为默认使用 ECMAScript 模块，除了node_modules 下面的文件夹和子文件夹，为了向后兼容。

在 --experimental-default-type=module 和 --experimental-wasm-modules 下，没有扩展名的文件如果以 WebAssembly 魔数 (\0asm) 开头，将被视为 WebAssembly；否则将被视为 ES 模块 JavaScript。

--experimental-detect-module#

Node.js 将检查不明确输入的源代码以确定它是否包含 ES 模块语法；如果检测到此类语法，则输入将被视为 ES 模块。

不明确输入定义为

• 具有 .js 扩展名或没有扩展名的文件；以及没有控制 package.json 文件或缺少 type 字段的文件；并且未指定 --experimental-default-type。
• 当未指定 --input-type 或 --experimental-default-type 时，字符串输入 (--eval 或 STDIN)。

ES 模块语法定义为在作为 CommonJS 评估时会抛出异常的语法。这包括 import 和 export 语句以及 import.meta 引用。它不包括 import() 表达式，它们在 CommonJS 中是有效的。

--experimental-import-meta-resolve#

启用实验性 import.meta.resolve() 父 URL 支持，允许传递第二个 parentURL 参数以进行上下文解析。

以前对整个 import.meta.resolve 功能进行了限制。

--experimental-loader=module#

此标志不建议使用，可能会在 Node.js 的未来版本中删除。请改用 --import 与 register()。

指定包含已导出 模块自定义钩子 的 module。module 可以是作为 import 指定符 接受的任何字符串。

--experimental-network-imports#

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

--experimental-permission#

为当前进程启用权限模型。启用后，以下权限将受到限制

• 文件系统 - 可通过 --allow-fs-read、--allow-fs-write 标志进行管理
• 子进程 - 可通过 --allow-child-process 标志进行管理
• 工作线程 - 可通过 --allow-worker 标志进行管理

--experimental-policy#

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

--experimental-sea-config#

使用此标志生成一个可以注入到 Node.js 二进制文件中的 blob，以生成一个 单一可执行应用程序。有关详细信息，请参阅有关 此配置 的文档。

--experimental-shadow-realm#

使用此标志启用 ShadowRealm 支持。

--experimental-test-coverage#

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

--experimental-vm-modules#

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

--experimental-wasi-unstable-preview1#

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

--experimental-wasm-modules#

启用实验性的 WebAssembly 模块支持。

--experimental-websocket#

启用实验性的 WebSocket 支持。

--force-context-aware#

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

--force-fips#

在启动时强制使用符合 FIPS 的加密。 （无法从脚本代码中禁用。）（与 --enable-fips 相同的要求。）

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

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

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

--frozen-intrinsics#

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

仅支持根上下文。无法保证 globalThis.Array 确实是默认的内建函数引用。代码在此标志下可能会出现故障。

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

--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生成的堆配置文件的文件名。

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

-h, --help#

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

--icu-data-dir=file#

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

--import=module#

在启动时预加载指定的模块。如果该标志被多次提供，每个模块将按其出现的顺序依次执行，从在 NODE_OPTIONS 中提供的模块开始。

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

--input-type=type#

此配置使 Node.js 将 --eval 或 STDIN 输入解释为 CommonJS 或 ES 模块。有效值为 "commonjs" 或 "module"。默认值为 "commonjs"，除非使用 --experimental-default-type=module。

REPL 不支持此选项。使用 --input-type=module 与 --print 一起使用将抛出错误，因为 --print 不支持 ES 模块语法。

--insecure-http-parser#

在 HTTP 解析器上启用宽松标志。这可能允许与不符合标准的 HTTP 实现进行互操作。

启用后，解析器将接受以下内容

• 无效的 HTTP 头部值。
• 无效的 HTTP 版本。
• 允许包含 Transfer-Encoding 和 Content-Length 头部的消息。
• 当 Connection: close 存在时，允许消息后有额外数据。
• 允许在提供 chunked 后有额外的传输编码。
• 允许使用 \n 作为标记分隔符，而不是 \r\n。
• 允许在块后不提供 \r\n。
• 允许在块大小后和 \r\n 之前存在空格。

以上所有操作都会使您的应用程序暴露于请求走私或中毒攻击。请避免使用此选项。

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

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

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

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

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

如果指定主机，请确保：

• 主机无法从公共网络访问。
• 防火墙禁止端口上的非预期连接。

更具体地说，如果端口（默认情况下为 9229）没有防火墙保护，则 --inspect=0.0.0.0 是不安全的。

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

--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-publish-uid=stderr,http#

指定检查器 Web 套接字 URL 公开的方式。

默认情况下，检查器 Web 套接字 URL 在 stderr 中可用，并且在 http://host:port/json/list 上的 /json/list 端点下可用。

-i, --interactive#

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

--jitless#

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

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

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

--napi-modules#

此选项是无操作的。它保留用于兼容性。

--no-addons#

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

--no-deprecation#

静默弃用警告。

--no-experimental-fetch#

禁用在全局范围内公开 Fetch API。

--no-experimental-global-customevent#

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

--no-experimental-global-navigator#

禁用在全局范围内公开 Navigator API。

--no-experimental-global-webcrypto#

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

--no-experimental-repl-await#

使用此标志禁用 REPL 中的顶层 await。

--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-network-family-autoselection#

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

--no-warnings#

静默所有进程警告（包括弃用警告）。

--node-memory-debug#

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

--openssl-config=file#

在启动时加载 OpenSSL 配置文件。除其他用途外，这可用于启用 FIPS 兼容加密，如果 Node.js 是针对 FIPS 启用的 OpenSSL 构建的。

--openssl-legacy-provider#

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

--openssl-shared-config#

启用 OpenSSL 默认配置部分，openssl_conf 从 OpenSSL 配置文件读取。默认配置文件名为 openssl.cnf，但可以使用环境变量 OPENSSL_CONF 或命令行选项 --openssl-config 更改。默认 OpenSSL 配置文件的位置取决于 OpenSSL 与 Node.js 的链接方式。共享 OpenSSL 配置可能会产生不希望有的影响，建议使用特定于 Node.js 的配置部分，即 nodejs_conf，当不使用此选项时，它是默认配置。

--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-main 与 --preserve-symlinks 一起使用。

有关更多信息，请参阅 --preserve-symlinks。

-p, --print "script"#

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

--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 堆栈很有用。

-r, --require module#

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

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

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

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

测试运行器 CLI 将并发执行的测试文件最大数量。默认值为 os.availableParallelism() - 1。

--test-name-pattern#

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

--test-only#

配置测试运行器仅执行已设置 only 选项的顶级测试。

--test-reporter#

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

--test-reporter-destination#

对应测试报告器的目标。有关详细信息，请参阅有关 测试报告器 的文档。

--test-shard#

要执行的测试套件分片，格式为 <index>/<total>，其中

index 是一个正整数，表示分片索引 total 是一个正整数，表示分片总数 此命令将把所有测试文件分成 total 个相等的部分，并将仅运行恰好位于 index 部分中的那些测试文件。

例如，要将您的测试套件分成三个部分，请使用以下命令

node --test --test-shard=1/3
node --test --test-shard=2/3
node --test --test-shard=3/3 copy

--test-timeout#

测试执行将在其后失败的毫秒数。如果未指定，子测试将从其父级继承此值。默认值为 Infinity。

--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.2 的安全性不如 TLSv1.3。

--trace-atomics-wait#

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

(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 数量相同，但在虚拟机或容器等环境中可能会有所不同。

-v, --version#

打印 node 的版本。

--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 实例清零。

环境变量#

FORCE_COLOR=[1, 2, 3]#

FORCE_COLOR 环境变量用于启用 ANSI 彩色输出。其值可以为

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

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

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

NO_COLOR=<any>#

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_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.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 选项是

• --allow-addons
• --allow-child-process
• --allow-fs-read
• --allow-fs-write
• --allow-worker
• --conditions, -C
• --diagnostic-dir
• --disable-proto
• --disable-warning
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --experimental-abortcontroller
• --experimental-default-type
• --experimental-detect-module
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-network-imports
• --experimental-permission
• --experimental-policy
• --experimental-shadow-realm
• --experimental-specifier-resolution
• --experimental-top-level-await
• --experimental-vm-modules
• --experimental-wasi-unstable-preview1
• --experimental-wasm-modules
• --experimental-websocket
• --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-global-customevent
• --no-experimental-global-navigator
• --no-experimental-global-webcrypto
• --no-experimental-repl-await
• --no-extra-info-on-fatal-exception
• --no-force-async-hooks-checks
• --no-global-search-paths
• --no-network-family-autoselection
• --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
• --test-shard
• --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_EXTERNAL_MODULE=file#

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

NODE_REPL_HISTORY=file#

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

NODE_SKIP_PLATFORM_CHECK=value#

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

NODE_TEST_CONTEXT=value#

如果 value 等于 'child'，则测试报告器选项将被覆盖，测试输出将以 TAP 格式发送到标准输出。如果提供任何其他值，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 可以设置为一个空字符串，以防止传播。

覆盖率输出#

覆盖率输出为 ScriptCoverage 对象的数组，位于顶层键 result 上

{
  "result": [
    {
      "scriptId": "67",
      "url": "internal/tty.js",
      "functions": []
    }
  ]
} copy

源映射缓存#

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

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

OPENSSL_CONF=file#

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

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

SSL_CERT_DIR=dir#

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

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

SSL_CERT_FILE=file#

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

请注意，除非显式设置子环境，否则此环境变量将被任何子进程继承，如果它们使用 OpenSSL，则可能会导致它们信任与 node 相同的 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 创建异步节点 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 线程池文档。

UV_USE_IO_URING=value#

在支持的平台上启用或禁用 libuv 使用 io_uring。

在支持的平台上，io_uring 可以显著提高各种异步 I/O 操作的性能。

由于安全问题，io_uring 默认情况下处于禁用状态。当启用 io_uring 时，应用程序在运行时不得更改进程的用户身份。在这种情况下，JavaScript 函数（如 process.setuid()）不可用，并且原生插件不得调用系统函数（如 setuid(2)）。

此环境变量由 Node.js 的依赖项实现，可能会在 Node.js 的未来版本中删除。此环境变量的行为没有提供任何稳定性保证。

有用的 V8 选项#

V8 有自己的 CLI 选项集。提供给 node 的任何 V8 CLI 选项都将传递给 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 copy

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

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

由于 V8 堆的年轻代大小是半空间大小的三倍（参见 V8 中的 YoungGenerationSizeFromSemiSpaceSize），半空间增加 1 MiB 会导致每个半空间增加 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