Node.js v25.0.0 文档

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

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

• 对于扩展名为 .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.fork() API 会从父进程继承执行参数。这意味着如果 Node.js 在启用权限模型和设置了 --allow-child-process 标志的情况下启动，任何使用 child_process.fork() 创建的子进程都将自动接收所有相关的权限模型标志。

此行为也适用于 child_process.spawn()，但在这种情况下，标志是通过 NODE_OPTIONS 环境变量传播的，而不是直接通过进程参数。

--allow-fs-read#

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

--allow-fs-read 标志的有效参数是：

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

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

初始化模块和自定义的 --require 模块具有隐式的读取权限。

$ node --permission -r custom-require.js -r custom-require-2.js index.js copy

• custom-require.js、custom-require-2.js 和 index.js 将默认在允许读取的列表中。

process.has('fs.read', 'index.js'); // true
process.has('fs.read', 'custom-require.js'); // true
process.has('fs.read', 'custom-require-2.js'); // true copy

--allow-fs-write#

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

--allow-fs-write 标志的有效参数是：

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

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

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

--allow-inspector#

使用权限模型时，进程将无法通过检查器协议进行连接。

任何这样做的尝试都会抛出 ERR_ACCESS_DENIED 错误，除非用户在启动 Node.js 时明确传递 --allow-inspector 标志。

示例

const { Session } = require('node:inspector/promises');

const session = new Session();
session.connect(); copy

$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions.
  code: 'ERR_ACCESS_DENIED',
} copy

--allow-net#

使用权限模型时，进程默认无法访问网络。任何这样做的尝试都会抛出 ERR_ACCESS_DENIED 错误，除非用户在启动 Node.js 时明确传递 --allow-net 标志。

示例

const http = require('node:http');
// Attempt to bypass the permission
const req = http.get('http://example.com', () => {});

req.on('error', (err) => {
  console.log('err', err);
}); copy

$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions.
  code: 'ERR_ACCESS_DENIED',
} copy

--allow-wasi#

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

示例

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#

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

示例

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）并将其写入磁盘，之后可以通过 --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> 必需。提供在构建快照之前执行的脚本名称，就像将 --build-snapshot 与 builder 作为主脚本名称一起传递一样。
• withoutCodeCache <boolean> 可选。包含代码缓存可以减少编译快照中包含的函数所花费的时间，但代价是快照尺寸更大，并可能破坏快照的可移植性。

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

-c, --check#

检查脚本的语法而不执行。

--completion-bash#

打印可用于 source 的 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-name，提供的值将用作文件名的模板。以下占位符受支持，并将在运行时被替换：

• ${pid} — 当前进程 ID

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

例如，以下脚本会发出 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-wasm-trap-handler#

默认情况下，Node.js 启用基于陷阱处理程序的 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 标准的加密。（要求 Node.js 针对兼容 FIPS 的 OpenSSL 进行构建。）

--enable-network-family-autoselection#

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

--enable-source-maps#

为堆栈跟踪启用 Source Map 支持。

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

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

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

请注意，启用 source maps 可能会在访问 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=file#

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

--env-file=file#

从相对于当前目录的文件中加载环境变量，使它们在 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

如果你想从一个可能不存在的文件中加载环境变量，你可以改用 --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
  },
  "testRunner": {
    "test-isolation": "process"
  }
} copy

配置文件支持特定命名空间的选项

• nodeOptions 字段包含在 NODE_OPTIONS 中允许的 CLI 标志。

• 像 testRunner 这样的命名空间字段包含特定于该子系统的配置。

不支持空操作标志。目前并非所有 V8 标志都受支持。

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

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

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

配置的优先级如下：

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

配置文件中的值不会覆盖环境变量和命令行选项中的值，但会覆盖由 --env-file 标志解析的 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-inspector-network-resource#

为检查器网络资源启用实验性支持。

--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 评估该模块，尝试定位顶层 await，并打印其位置以帮助用户找到它们。

--experimental-quic#

为 QUIC 协议启用实验性支持。

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

为使用 Chrome DevTools 进行工作线程检查启用实验性支持。

--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 确实是默认的内建引用。代码在此标志下可能会中断。

为了允许添加 polyfills，--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 时，它会尽力在 Node.js 实例耗尽内存之前至少生成一个，最多 max_count 个快照。

生成 V8 快照需要时间和内存（包括 V8 堆管理的内存和 V8 堆外的原生内存）。堆越大，需要的资源就越多。Node.js 将调整 V8 堆以适应额外的 V8 堆内存开销，并尽力避免用尽进程可用的所有内存。当进程使用的内存超过系统认为适当的量时，根据系统配置，进程可能会被系统突然终止。

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

<--- Last few GCs --->

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


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
.... 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"。当使用 --no-experimental-strip-types 标志时，"-typescript" 值不可用。默认值为无，如果传递了 --no-experimental-detect-module，则为 "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 以 --no-webstorage（或 --no-experimental-webstorage）标志启动，则此标志无效。

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

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

--max-old-space-size-percentage=percentage#

将 V8 老生代内存区域的最大内存大小设置为可用系统内存的百分比。当同时指定此标志和 --max-old-space-size 时，此标志优先。

percentage 参数必须是大于 0 且不超过 100 的数字，表示分配给 V8 堆的可用系统内存的百分比。

注意： 此标志利用 --max-old-space-size，由于整数溢出问题，在 32 位平台上可能不可靠。

# Using 50% of available system memory
node --max-old-space-size-percentage=50 index.js

# Using 75% of available system memory
node --max-old-space-size-percentage=75 index.js copy

--napi-modules#

此选项无效。保留它是为了兼容性。

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

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

--no-addons#

禁用 `node-addons` 导出条件以及禁用加载原生插件。当指定 `--no-addons` 时，调用 `process.dlopen` 或 `require` 一个原生 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#

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

--no-warnings#

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

--no-webstorage#

禁用 Web Storage 支持。

--node-memory-debug#

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

--openssl-config=file#

在启动时加载 OpenSSL 配置文件。除其他用途外，如果 Node.js 是针对启用 FIPS 的 OpenSSL 构建的，这可以用来启用符合 FIPS 标准的加密。

--openssl-legacy-provider#

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

--openssl-shared-config#

启用从 OpenSSL 配置文件中读取 OpenSSL 默认配置部分 openssl_conf。默认配置文件名为 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-net 标志管理
• 子进程 - 可通过 --allow-child-process 标志管理
• 工作线程 - 可通过 --allow-worker 标志管理
• WASI - 可通过 --allow-wasi 标志管理
• 插件 - 可通过 --allow-addons 标志管理

--preserve-symlinks#

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

默认情况下，当 Node.js 从一个符号链接到不同磁盘位置的路径加载模块时，Node.js 会解析该链接，并使用模块在磁盘上的实际“真实路径”作为标识符和定位其他依赖模块的根路径。在大多数情况下，这种默认行为是可以接受的。然而，当使用符号链接的对等依赖（peer dependencies）时，如下例所示，如果 moduleA 试图 require 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-exclude-env#

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

--report-exclude-network#

从诊断报告中排除 header.networkInterfaces。默认情况下不设置此项，网络接口会被包含在内。

--report-filename=filename#

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

如果文件名设置为 '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 或 inspector 结合使用。更多详情请参见从命令行运行测试的文档。

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

一个文件路径，允许测试运行器在多次运行之间持久化测试套件的状态。测试运行器将使用此文件来确定哪些测试已经成功或失败，从而可以重新运行失败的测试，而无需重新运行整个测试套件。如果文件不存在，测试运行器将创建它。更多详情请参见测试重跑的文档。

--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 密码列表。要求 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.3 安全的 TLSv1.2 的支持。

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

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

这等同于设置 NODE_USE_ENV_PROXY=1 环境变量。当两者都设置时，--use-env-proxy 优先。

--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 从 Node.js 链接的 OpenSSL 版本所遵循的默认证书文件（通常是 /etc/ssl/cert.pem）和默认证书目录（通常是 /etc/ssl/certs）加载证书。这通常适用于主流 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 进程重新启动。默认情况下，监视模式将监视入口点以及任何被 require 或 import 的模块。使用 --watch-path 来指定要监视的路径。

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

注意：--watch 标志需要一个文件路径作为参数，并且与 --run 或内联脚本输入不兼容，因为 --run 优先并忽略监视模式。如果未提供文件，Node.js 将以状态码 9 退出。

node --watch index.js copy

--watch-kill-signal#

自定义在监视模式重新启动时发送给进程的信号。

node --watch --watch-kill-signal SIGINT test.js copy

--watch-path#

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

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

注意：使用 --watch-path 会隐式启用 --watch，后者需要一个文件路径并且与 --run 不兼容，因为 --run 优先并忽略监视模式。

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_COMPILE_CACHE_PORTABLE=1#

当设置为 1 时，只要模块布局相对于缓存目录保持不变，模块编译缓存就可以在不同的目录位置之间重用。

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

• --allow-addons
• --allow-child-process
• --allow-fs-read
• --allow-fs-write
• --allow-inspector
• --allow-net
• --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-quic
• --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
• --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
• --max-old-space-size-percentage
• --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-experimental-webstorage
• --no-extra-info-on-fatal-exception
• --no-force-async-hooks-checks
• --no-global-search-paths
• --no-network-family-autoselection
• --no-warnings
• --no-webstorage
• --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-rerun-failures
• --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-env-proxy
• --use-largepages
• --use-openssl-ca
• --use-system-ca
• --v8-pool-size
• --watch-kill-signal
• --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 环境变量，并通过指定的代理隧道传输请求。

也可以使用 --use-env-proxy 命令行标志来启用此功能。当两者都设置时，--use-env-proxy 优先。

NODE_USE_SYSTEM_CA=1#

Node.js 使用系统存储中存在的受信任 CA 证书，以及 --use-bundled-ca 选项和 NODE_EXTRA_CA_CERTS 环境变量。

也可以使用 --use-system-ca 命令行标志来启用此功能。当两者都设置时，--use-system-ca 优先。

NODE_V8_COVERAGE=dir#

设置后，Node.js 将开始向作为参数提供的目录输出 V8 JavaScript 代码覆盖率和源映射数据（覆盖率信息以 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，可能会导致它们信任与 node 相同的 CA。

SSL_CERT_FILE=file#

如果启用了 --use-openssl-ca，或者在除 macOS 和 Windows 之外的平台上启用了 --use-system-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，但在它们不存在的情况下，会使用 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 线程池的大小。但是，在进程内部使用 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 scavenge 垃圾回收器的半空间最大大小，单位为 MiB (mebibytes)。增加半空间的最大大小可以提高 Node.js 的吞吐量，但会消耗更多内存。

由于 V8 堆的新生代大小是半空间大小的三倍（参见 V8 中的 YoungGenerationSizeFromSemiSpaceSize），半空间增加 1 MiB 会应用到三个独立的半空间中的每一个，并导致堆大小增加 3 MiB。吞吐量的提升取决于您的工作负载（参见 #42511）。

默认值取决于内存限制。例如，在内存限制为 512 MiB 的 64 位系统上，半空间的最大大小默认为 1 MiB。对于内存限制不超过 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