Node.js v24.0.0 文档

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

加载时，ES 模块加载器加载程序入口点，node 命令将仅接受带有 .js、.mjs 或 .cjs 扩展名的文件作为输入。 使用以下标志，将启用其他文件扩展名

• 对于带有 .wasm 扩展名的文件，请使用 --experimental-wasm-modules。
• 对于带有 .node 扩展名的文件，请使用 --experimental-addon-modules。

-#

stdin 的别名。类似于其他命令行实用程序中 - 的用法，表示脚本从 stdin 读取，其余选项传递给该脚本。

--#

指示 Node 选项的结束。将剩余的参数传递给脚本。如果在之前没有提供脚本文件名或 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 --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 --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 node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'ChildProcess'
} copy

与 child_process.spawn 不同，child_process.fork API 复制父进程的执行参数。这意味着，如果您在启用权限模型的情况下启动 Node.js 并包含 --allow-child-process 标志，则调用 child_process.fork() 会将所有权限模型标志传播到子进程。

--allow-fs-read#

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

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

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

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

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

$ node --permission index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:23:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'FileSystemRead',
  resource: '/Users/rafaelgss/repos/os/node/index.js'
} copy

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

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

--allow-fs-write#

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

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

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

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

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

--allow-wasi#

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

示例

const { WASI } = require('node:wasi');
// Attempt to bypass the permission
new WASI({
  version: 'preview1',
  // Attempt to mount the whole filesystem
  preopens: {
    '/': '/',
  },
}); copy

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:30:49 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WASI',
} copy

--allow-worker#

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

示例

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

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WorkerThreads'
} copy

--build-snapshot#

在进程退出时生成快照 blob 并将其写入磁盘，该快照 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"、"default"、"import" 和 "require" 的默认 Node.js 条件将始终按定义应用。

例如，要使用“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-name，则提供的值将按原样使用； 不支持诸如 ${hhmmss} 或 ${pid} 之类的模式。

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js
$ ls *.cpuprofile
'CPU.${pid}.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 的异常。

--disable-sigusr1#

禁用通过向进程发送 SIGUSR1 信号来启动调试会话的功能。

--disable-warning=code-or-type#

按 code 或 type 禁用特定的进程警告。

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

弃用警告列表。

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

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

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

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

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-wasm-trap-handler#

默认情况下，Node.js 启用基于 trap-handler 的 WebAssembly 边界检查。 因此，V8 不需要在从 WebAssembly 编译的代码中插入内联边界检查，这可能会显着加速 WebAssembly 的执行，但此优化需要分配一个大的虚拟内存容器（目前为 10GB）。 如果 Node.js 进程由于系统配置或硬件限制而无法访问足够大的虚拟内存地址空间，则用户将无法运行任何涉及在此虚拟内存容器中分配的 WebAssembly，并且会看到内存不足错误。

$ ulimit -v 5000000
$ node -p "new WebAssembly.Memory({ initial: 10, maximum: 100 });"
[eval]:1
new WebAssembly.Memory({ initial: 10, maximum: 100 });
^

RangeError: WebAssembly.Memory(): could not allocate memory
    at [eval]:1:1
    at runScriptInThisContext (node:internal/vm:209:10)
    at node:internal/process/execution:118:14
    at [eval]-wrapper:6:24
    at runScript (node:internal/process/execution:101:62)
    at evalScript (node:internal/process/execution:136:3)
    at node:internal/main/eval_string:49:3
 copy

--disable-wasm-trap-handler 禁用此优化，以便当 Node.js 进程可用的虚拟内存地址空间低于 V8 WebAssembly 内存容器的需求时，用户至少可以运行 WebAssembly（性能欠佳）。

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

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

--dns-result-order=order#

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

• ipv4first: 将默认 order 设置为 ipv4first。
• ipv6first: 将默认 order 设置为 ipv6first。
• verbatim: 将默认 order 设置为 verbatim。

默认值为 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 启用 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 的性能影响。

--entry-url#

如果存在，Node.js 会将入口点解释为 URL，而不是路径。

遵循 ECMAScript 模块 解析规则。

URL 中的任何查询参数或哈希值都将通过 import.meta.url 访问。

node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'
node --entry-url 'file.ts?query#hash'
node --entry-url 'data:text/javascript,console.log("Hello")' copy

--env-file-if-exists=config#

行为与 --env-file 相同，但如果文件不存在，则不会抛出错误。

--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 USERNAME="nodejs" # will result in `nodejs` as the value. copy

如果要从可能不存在的文件加载环境变量，则可以使用 --env-file-if-exists 标志。

-e, --eval "script"#

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

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

可以运行包含内联类型的代码，除非提供 --no-experimental-strip-types 标志。

--experimental-addon-modules#

为 .node 插件启用实验性导入支持。

--experimental-config-file=config#

如果存在，Node.js 将在指定路径中查找配置文件。 Node.js 将读取配置文件并应用设置。 配置文件应为具有以下结构的 JSON 文件。 $schema 中的 vX.Y.Z 必须替换为您正在使用的 Node.js 版本。

{
  "$schema": "https://node.org.cn/dist/vX.Y.Z/docs/node-config-schema.json",
  "nodeOptions": {
    "import": [
      "amaro/strip"
    ],
    "watch-path": "src",
    "watch-preserve-output": true
  }
} copy

在 nodeOptions 字段中，仅支持 NODE_OPTIONS 中允许的标志。 不支持空操作标志。 并非所有 V8 标志当前都受支持。

可以使用 官方 JSON 模式来验证配置文件，这可能会因 Node.js 版本而异。 配置文件中的每个键都对应于可以作为命令行参数传递的标志。 键的值将传递给标志的值。

例如，上面的配置文件等效于以下命令行参数

node --import amaro/strip --watch-path=src --watch-preserve-output copy

配置中的优先级如下

1. NODE_OPTIONS 和命令行选项
2. 配置文件
3. Dotenv NODE_OPTIONS

配置文件中的值不会覆盖环境变量和命令行选项中的值，但会覆盖由 --env-file 标志解析的 NODE_OPTIONS env 文件中的值。

如果配置文件中存在重复的键，则只会使用第一个键。

如果配置文件包含未知键或无法在 NODE_OPTIONS 中使用的键，则配置解析器将抛出错误。

Node.js 不会对用户提供的配置进行清理或执行验证，因此 切勿 使用不受信任的配置文件。

--experimental-default-config-file#

如果存在 --experimental-default-config-file 标志，Node.js 将在当前工作目录中查找 node.config.json 文件，并将其加载为配置文件。

--experimental-eventsource#

启用在全局作用域中暴露 EventSource Web API。

--experimental-import-meta-resolve#

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

以前控制整个 import.meta.resolve 功能。

--experimental-loader=module#

不鼓励使用此标志，并且可能会在 Node.js 的未来版本中删除。请改用 带有 register() 的 --import。

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

如果此功能与权限模型一起使用，则需要 --allow-worker。

--experimental-network-inspection#

启用对使用 Chrome DevTools 进行网络检查的实验性支持。

--experimental-print-required-tla#

如果正在 require() 的 ES 模块包含顶层 await，则此标志允许 Node.js 评估该模块，尝试定位顶层 awaits，并打印它们的位置以帮助用户找到它们。

--experimental-require-module#

支持在 require() 中加载同步 ES 模块图。

请参阅使用 require() 加载 ECMAScript 模块。

--experimental-sea-config#

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

--experimental-shadow-realm#

使用此标志启用 ShadowRealm 支持。

--experimental-test-coverage#

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

--experimental-test-module-mocks#

在测试运行器中启用模块模拟。

如果此功能与权限模型一起使用，则需要 --allow-worker。

--experimental-transform-types#

启用将仅 TypeScript 语法转换为 JavaScript 代码。 意味着 --enable-source-maps。

--experimental-vm-modules#

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

--experimental-wasi-unstable-preview1#

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

--experimental-wasm-modules#

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

--experimental-webstorage#

启用实验性的 Web Storage 支持。

--expose-gc#

此标志将暴露来自 V8 的 gc 扩展。

if (globalThis.gc) {
  globalThis.gc();
} copy

--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 个快照到磁盘，但当 max_count 大于 0 时，它将尽力生成至少一个且最多 max_count 个快照，然后 Node.js 实例耗尽内存。

生成 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"、"module-typescript" 和 "commonjs-typescript"。"-typescript" 值不能与标志 --no-experimental-strip-types 一起使用。默认值为 "commonjs"。

如果未提供 --input-type，Node.js 将尝试使用以下步骤检测语法

1. 将输入作为 CommonJS 运行。
2. 如果步骤 1 失败，则将输入作为 ES 模块运行。
3. 如果步骤 2 因 SyntaxError 而失败，则剥离类型。
4. 如果步骤 3 失败，并且错误代码为 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX 或 ERR_INVALID_TYPESCRIPT_SYNTAX，则抛出步骤 2 中的错误，包括消息中的 TypeScript 错误，否则作为 CommonJS 运行。
5. 如果步骤 4 失败，则将输入作为 ES 模块运行。

为了避免多次语法检测过程的延迟，可以使用 --input-type=type 标志来指定应如何解释 --eval 输入。

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-brk[=[host:]port]#

在 host:port 上激活检查器，并在用户脚本的开头中断。默认的 host:port 是 127.0.0.1:9229。如果指定端口 0，将使用一个随机的可用端口。

有关 Node.js 调试器的更多说明，请参阅 Node.js 的 V8 检查器集成。

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

设置激活检查器时要使用的 host:port。通过发送 SIGUSR1 信号激活检查器时很有用。除非传递了 --disable-sigusr1。

默认主机为 127.0.0.1。如果指定端口 0，将使用一个随机的可用端口。

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

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

指定检查器 web socket URL 暴露的方式。

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

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

在 host:port 上激活检查器，并等待调试器连接。默认的 host:port 是 127.0.0.1:9229。如果指定端口 0，将使用一个随机的可用端口。

有关 Node.js 调试器的更多说明，请参阅 Node.js 的 V8 检查器集成。

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

在 host:port 上激活检查器。默认值为 127.0.0.1:9229。如果指定端口 0，将使用一个随机的可用端口。

V8 检查器集成允许诸如 Chrome DevTools 和 IDE 之类的工具调试和分析 Node.js 实例。这些工具通过 tcp 端口连接到 Node.js 实例，并使用 Chrome DevTools 协议进行通信。有关 Node.js 调试器的更多说明，请参阅 Node.js 的 V8 检查器集成。

-i, --interactive#

即使 stdin 似乎不是终端，也打开 REPL。

--jitless#

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

--localstorage-file=file#

用于存储 localStorage 数据的文件。如果该文件不存在，则在第一次访问 localStorage 时创建。多个 Node.js 进程可以并发共享同一个文件。除非 Node.js 使用 --experimental-webstorage 标志启动，否则此标志不起作用。

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

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

--napi-modules#

此选项不起作用。保留它是为了兼容性。

--network-family-autoselection-attempt-timeout#

设置网络族自动选择尝试超时的默认值。有关更多信息，请参见 net.getDefaultAutoSelectFamilyAttemptTimeout()。

--no-addons#

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

--no-async-context-frame#

禁用由 AsyncContextFrame 支持的 AsyncLocalStorage 的使用，并使用依赖于 async_hooks 的先前实现。为了与 Electron 兼容以及在上下文流可能不同的情况下，保留了以前的模型。但是，如果发现流程有差异，请报告它。

--no-deprecation#

禁止显示弃用警告。

--no-experimental-detect-module#

禁用使用 语法检测 来确定模块类型。

--no-experimental-global-navigator#

禁用全局作用域上 Navigator API 的公开。

--no-experimental-repl-await#

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

--no-experimental-require-module#

禁用在 require() 中加载同步 ES 模块图的支持。

请参阅使用 require() 加载 ECMAScript 模块。

--no-experimental-sqlite#

禁用实验性的 node:sqlite 模块。

--no-experimental-strip-types#

禁用 TypeScript 文件的实验性类型剥离。有关更多信息，请参阅 TypeScript 类型剥离 文档。

--no-experimental-websocket#

禁用全局作用域上 WebSocket 的公开。

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

禁用 family 自动选择算法，除非连接选项显式启用它。

--no-warnings#

屏蔽所有进程警告（包括弃用）。

--node-memory-debug#

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

--openssl-config=file#

在启动时加载 OpenSSL 配置文件。 除其他用途外，如果 Node.js 是基于启用 FIPS 的 OpenSSL 构建的，则可以使用它来启用符合 FIPS 的加密。

--openssl-legacy-provider#

启用 OpenSSL 3.0 legacy provider。 更多信息请参见 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 用法。

--permission#

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

• 文件系统 - 可通过 --allow-fs-read, --allow-fs-write 标志进行管理
• 子进程 - 可通过 --allow-child-process 标志进行管理
• Worker 线程 - 可通过 --allow-worker 标志进行管理
• WASI - 可通过 --allow-wasi 标志进行管理
• 插件 - 可通过 --allow-addons 标志进行管理

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

-p, --print "script"#

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

--prof#

生成 V8 profiler 输出。

--prof-process#

处理使用 V8 选项 --prof 生成的 V8 profiler 输出。

--redirect-warnings=file#

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

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

--report-compact#

以紧凑格式写入报告，单行 JSON，比默认的多行格式（专为人类消费而设计）更容易被日志处理系统使用。

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

报告将生成的位置。

--report-exclude-env#

当传递 --report-exclude-env 时，生成的诊断报告将不包含 environmentVariables 数据。

--report-exclude-network#

从诊断报告中排除 header.networkInterfaces。 默认情况下，此设置未设置，并且包含网络接口。

--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 可以是文件路径，也可以是 node 模块名。

使用 --require 预加载的模块将在使用 --import 预加载的模块之前运行。

模块会被预加载到主线程以及任何工作线程、派生进程或集群进程中。

--run#

这会从 package.json 的 "scripts" 对象运行指定的命令。 如果提供了缺少的 "command"，它将列出可用的脚本。

--run 将向上遍历到根目录并找到一个 package.json 文件以从中运行命令。

--run 将 ./node_modules/.bin 添加到当前目录的每个祖先的 PATH 前面，以便从存在多个 node_modules 目录的不同文件夹执行二进制文件（如果 ancestor-folder/node_modules/.bin 是一个目录）。

--run 在包含相关 package.json 的目录中执行命令。

例如，以下命令将运行当前文件夹中 package.json 的 test 脚本

$ node --run test copy

您还可以将参数传递给命令。 -- 之后的任何参数都将附加到脚本

$ node --run test -- --verbose copy

--secure-heap-min=n#

当使用 --secure-heap 时，--secure-heap-min 标志指定从安全堆进行的最小分配量。 最小值是 2。 最大值是 --secure-heap 或 2147483647 中较小的一个。 给定的值必须是 2 的幂。

--secure-heap=n#

初始化一个大小为 n 字节的 OpenSSL 安全堆。 初始化后，安全堆用于密钥生成和其他操作期间 OpenSSL 中选定类型的分配。 例如，这对于防止由于指针溢出或下溢而导致敏感信息泄漏非常有用。

安全堆的大小是固定的，无法在运行时调整大小，因此，如果使用，选择足够大的堆以覆盖所有应用程序使用非常重要。

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

默认情况下禁用安全堆。

安全堆在 Windows 上不可用。

有关更多详细信息，请参阅 CRYPTO_secure_malloc_init。

--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 将并发执行的最大测试文件数。 如果 --test-isolation 设置为 'none'，则忽略此标志，并且并发度为 1。 否则，并发度默认为 os.availableParallelism() - 1。

--test-coverage-branches=threshold#

需要最小百分比的覆盖分支。 如果代码覆盖率未达到指定的阈值，则进程将以代码 1 退出。

--test-coverage-exclude#

使用 glob 模式从代码覆盖率中排除特定文件，该模式可以匹配绝对和相对文件路径。

可以多次指定此选项以排除多个 glob 模式。

如果同时提供了 --test-coverage-exclude 和 --test-coverage-include，则文件必须满足两个条件才能包含在覆盖率报告中。

默认情况下，所有匹配的测试文件都将从覆盖率报告中排除。 指定此选项将覆盖默认行为。

--test-coverage-functions=threshold#

需要最小百分比的覆盖函数。 如果代码覆盖率未达到指定的阈值，则进程将以代码 1 退出。

--test-coverage-include#

使用 glob 模式将特定文件包含在代码覆盖率中，该模式可以匹配绝对和相对文件路径。

可以多次指定此选项以包含多个 glob 模式。

如果同时提供了 --test-coverage-exclude 和 --test-coverage-include，则文件必须满足两个条件才能包含在覆盖率报告中。

--test-coverage-lines=threshold#

需要最小百分比的覆盖行。 如果代码覆盖率未达到指定的阈值，则进程将以代码 1 退出。

--test-force-exit#

配置测试运行器，以便在所有已知测试完成执行后退出进程，即使事件循环在其他情况下仍保持活动状态。

--test-global-setup=module#

指定一个模块，该模块将在执行所有测试之前进行评估，并且可以用于设置全局状态或测试的固件。

有关更多详细信息，请参阅有关全局设置和拆卸的文档。

--test-isolation=mode#

配置测试运行器中使用的测试隔离的类型。 当 mode 为 'process' 时，每个测试文件都在单独的子进程中运行。 当 mode 为 'none' 时，所有测试文件都与测试运行器在同一进程中运行。 默认隔离模式是 'process'。 如果不存在 --test 标志，则忽略此标志。 有关更多信息，请参阅 测试运行器执行模型 部分。

--test-name-pattern#

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

如果同时提供了 --test-name-pattern 和 --test-skip-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-skip-pattern#

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

如果同时提供了 --test-name-pattern 和 --test-skip-pattern，则测试必须满足两个要求才能执行。

--test-timeout#

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

--test-update-snapshots#

重新生成测试运行器用于快照测试的快照文件。

--throw-deprecation#

对弃用抛出错误。

--title=title#

在启动时设置 process.title。

--tls-cipher-list=list#

指定备用默认 TLS 密码列表。 需要使用 crypto 支持构建 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-deprecation#

打印弃用的堆栈跟踪。

--trace-env#

将当前 Node.js 实例中对环境变量的任何访问信息打印到 stderr，包括

• Node.js 内部执行的环境变量读取。
• process.env.KEY = "SOME VALUE" 形式的写入。
• process.env.KEY 形式的读取。
• Object.defineProperty(process.env, 'KEY', {...}) 形式的定义。
• Object.hasOwn(process.env, 'KEY')、process.env.hasOwnProperty('KEY') 或 'KEY' in process.env 形式的查询。
• delete process.env.KEY 形式的删除。
• ...process.env 或 Object.keys(process.env) 形式的枚举。

仅打印被访问的环境变量的名称。 不打印值。

要打印访问的堆栈跟踪，请使用 --trace-env-js-stack 和/或 --trace-env-native-stack。

--trace-env-js-stack#

除了 --trace-env 所做的之外，这还会打印访问的 JavaScript 堆栈跟踪。

--trace-env-native-stack#

除了 --trace-env 所做的之外，这还会打印访问的本机堆栈跟踪。

--trace-event-categories#

一个逗号分隔的类别列表，当使用 --trace-events-enabled 启用跟踪事件跟踪时，应该跟踪这些类别。

--trace-event-file-pattern#

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

--trace-events-enabled#

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

--trace-exit#

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

--trace-require-module=mode#

打印关于使用 使用 require() 加载 ECMAScript 模块的信息。

当 mode 为 all 时，将打印所有使用情况。 当 mode 为 no-node-modules 时，将排除来自 node_modules 文件夹的使用情况。

--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：如果操作系统支持，将尝试映射。 映射失败将被忽略，并且不会报告。

--use-system-ca#

Node.js 使用系统存储中的可信 CA 证书，同时使用 --use-bundled-ca 选项和 NODE_EXTRA_CA_CERTS 环境变量。在 Windows 和 macOS 以外的平台上，这会从 OpenSSL 信任的目录和文件加载证书，类似于 --use-openssl-ca，不同之处在于它会在首次加载后缓存证书。

在 Windows 和 macOS 上，证书信任策略计划遵循 Chromium 的本地信任证书策略

在 macOS 上，以下设置会被考虑：

• 默认和系统钥匙串
  • 信任
    • 任何“使用此证书时”标志设置为“始终信任”的证书，或
    • 任何“安全套接层 (SSL)”标志设置为“始终信任”的证书。
  • 不信任
    • 任何“使用此证书时”标志设置为“从不信任”的证书，或
    • 任何“安全套接层 (SSL)”标志设置为“从不信任”的证书。

在 Windows 上，以下设置会被考虑（与 Chromium 的策略不同，目前不支持不信任和中间 CA）：

• 本地计算机（通过 certlm.msc 访问）
  • 信任
    • 受信任的根证书颁发机构
    • 受信任的人员
    • 企业信任 -> 企业 -> 受信任的根证书颁发机构
    • 企业信任 -> 企业 -> 受信任的人员
    • 企业信任 -> 组策略 -> 受信任的根证书颁发机构
    • 企业信任 -> 组策略 -> 受信任的人员
• 当前用户（通过 certmgr.msc 访问）
  • 信任
    • 受信任的根证书颁发机构
    • 企业信任 -> 组策略 -> 受信任的根证书颁发机构

在 Windows 和 macOS 上，Node.js 会检查证书的用户设置是否禁止它们用于 TLS 服务器身份验证，然后才会使用它们。

在其他系统上，Node.js 从默认证书文件（通常是 /etc/ssl/cert.pem）和默认证书目录（通常是 /etc/ssl/certs）加载证书，这些文件和目录是 Node.js 链接到的 OpenSSL 版本所信任的。这通常适用于主要的 Linux 发行版和其他类 Unix 系统上的约定。如果覆盖 OpenSSL 的环境变量（通常是 SSL_CERT_FILE 和 SSL_CERT_DIR，具体取决于 Node.js 链接到的 OpenSSL 的配置）已设置，则将使用指定的路径来加载证书。如果 Node.js 链接到的 OpenSSL 版本使用的常规路径与用户出于某种原因的系统配置不一致，则可以使用这些环境变量作为解决方法。

--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 实例填充为零。

FORCE_COLOR=[1, 2, 3]#

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

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

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

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

NODE_COMPILE_CACHE=dir#

为 Node.js 实例启用模块编译缓存。 有关详细信息，请参阅模块编译缓存的文档。

NODE_DEBUG=module[,…]#

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

NODE_DEBUG_NATIVE=module[,…]#

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

NODE_DISABLE_COLORS=1#

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

NODE_DISABLE_COMPILE_CACHE=1#

为 Node.js 实例禁用模块编译缓存。 有关详细信息，请参阅模块编译缓存的文档。

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 选项在以下列表中。 如果一个选项支持 --XX 和 --no-XX 变体，则它们都受支持，但列表中只包含一个。

• --allow-addons
• --allow-child-process
• --allow-fs-read
• --allow-fs-write
• --allow-wasi
• --allow-worker
• --conditions, -C
• --cpu-prof-dir
• --cpu-prof-interval
• --cpu-prof-name
• --cpu-prof
• --diagnostic-dir
• --disable-proto
• --disable-sigusr1
• --disable-warning
• --disable-wasm-trap-handler
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --entry-url
• --experimental-abortcontroller
• --experimental-addon-modules
• --experimental-detect-module
• --experimental-eventsource
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-print-required-tla
• --experimental-require-module
• --experimental-shadow-realm
• --experimental-specifier-resolution
• --experimental-test-isolation
• --experimental-top-level-await
• --experimental-transform-types
• --experimental-vm-modules
• --experimental-wasi-unstable-preview1
• --experimental-wasm-modules
• --experimental-webstorage
• --force-context-aware
• --force-fips
• --force-node-api-uncaught-exceptions-policy
• --frozen-intrinsics
• --heap-prof-dir
• --heap-prof-interval
• --heap-prof-name
• --heap-prof
• --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-wait
• --inspect
• --localstorage-file
• --max-http-header-size
• --napi-modules
• --network-family-autoselection-attempt-timeout
• --no-addons
• --no-async-context-frame
• --no-deprecation
• --no-experimental-global-navigator
• --no-experimental-repl-await
• --no-experimental-sqlite
• --no-experimental-strip-types
• --no-experimental-websocket
• --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
• --permission
• --preserve-symlinks-main
• --preserve-symlinks
• --prof-process
• --redirect-warnings
• --report-compact
• --report-dir, --report-directory
• --report-exclude-env
• --report-exclude-network
• --report-filename
• --report-on-fatalerror
• --report-on-signal
• --report-signal
• --report-uncaught-exception
• --require, -r
• --secure-heap-min
• --secure-heap
• --snapshot-blob
• --test-coverage-branches
• --test-coverage-exclude
• --test-coverage-functions
• --test-coverage-include
• --test-coverage-lines
• --test-global-setup
• --test-isolation
• --test-name-pattern
• --test-only
• --test-reporter-destination
• --test-reporter
• --test-shard
• --test-skip-pattern
• --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-deprecation
• --trace-env-js-stack
• --trace-env-native-stack
• --trace-env
• --trace-event-categories
• --trace-event-file-pattern
• --trace-events-enabled
• --trace-exit
• --trace-require-module
• --trace-sigint
• --trace-sync-io
• --trace-tls
• --trace-uncaught
• --trace-warnings
• --track-heap-objects
• --unhandled-rejections
• --use-bundled-ca
• --use-largepages
• --use-openssl-ca
• --use-system-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
• --expose-gc
• --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 格式发送到 stdout。如果提供任何其他值，Node.js 不保证所使用的报告器格式或其稳定性。

NODE_TLS_REJECT_UNAUTHORIZED=value#

如果 value 等于 '0'，则禁用 TLS 连接的证书验证。这使得 TLS，以及 HTTPS 作为扩展，变得不安全。强烈建议不要使用此环境变量。

NODE_USE_ENV_PROXY=1#

启用后，Node.js 会在启动期间解析 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量，并通过指定的代理隧道请求。

目前，这只会影响通过 fetch() 发送的请求。对其他内置 http 和 https 方法的支持正在进行中。

NODE_V8_COVERAGE=dir#

如果设置，Node.js 将开始将 V8 JavaScript 代码覆盖率和 Source Map 数据输出到作为参数提供的目录（覆盖率信息作为 JSON 写入到带有 coverage 前缀的文件）。

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

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

{
  "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，或者如果在 macOS 和 Windows 以外的平台上启用了 --use-system-ca，这将覆盖并设置 OpenSSL 的目录，其中包含受信任的证书。

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

SSL_CERT_FILE=file#

如果启用了 --use-openssl-ca，或者如果在 macOS 和 Windows 以外的平台上启用了 --use-system-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 个线程。

异步系统 API 尽可能地被 Node.js 使用，但在不存在异步系统 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 线程池的大小。 但是，使用 process.env.UV_THREADPOOL_SIZE=size 从进程内部进行设置不能保证有效，因为线程池可能已经在用户代码运行之前就作为运行时初始化的一部分创建了。 更多信息，请参阅 libuv 线程池文档。

--abort-on-uncaught-exception#

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

--enable-etw-stack-walking#

--expose-gc#

--harmony-shadow-realm#

--interpreted-frames-native-stack#

--jitless#

--max-old-space-size=SIZE (以 MiB 为单位)#

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

在一台拥有 2 GiB 内存的机器上，考虑将其设置为 1536 (1.5 GiB)，以便为其他用途留下一些内存并避免交换。

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

--max-semi-space-size=SIZE (单位：MiB)#

设置 V8 半空间大小的最大值，用于 V8 的 scavenge 垃圾回收器，单位为 MiB（兆字节）。 增加半空间的最大大小可以提高 Node.js 的吞吐量，但会增加内存消耗。

由于 V8 堆的年轻代大小是半空间的 3 倍（请参阅 V8 中的 YoungGenerationSizeFromSemiSpaceSize），因此半空间增加 1 MiB 会影响每个独立的半空间，并导致堆大小增加 3 MiB。 吞吐量改进取决于您的工作负载（请参阅 #42511）。

默认值取决于内存限制。 例如，在内存限制为 512 MiB 的 64 位系统上，半空间的最大大小默认为 1 MiB。 对于高达 2GiB（包括 2GiB）的内存限制，64 位系统上半空间的最大默认大小将小于 16 MiB。

为了获得应用程序的最佳配置，您应该在为应用程序运行基准测试时尝试不同的 max-semi-space-size 值。

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

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

--perf-basic-prof#

--perf-basic-prof-only-functions#

--perf-prof#

--perf-prof-unwinding-info#

--prof#

--security-revert#

--stack-trace-limit=limit#

在错误的堆栈跟踪中收集的最大堆栈帧数。 将其设置为 0 会禁用堆栈跟踪收集。 默认值为 10。

node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 copy