命令行 API

Node.js 提供了多种 CLI 选项。这些选项公开了内置的调试功能、多种执行脚本的方法以及其他有用的运行时选项。

要在终端中将此文档作为手册页查看，请运行 man node。

概要

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 模块加载器解析。如果找不到相应的文件，则会抛出错误。

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

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

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

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

加载时，ES 模块加载器将加载程序入口点，node 命令仅接受扩展名为 .js、.mjs 或 .cjs 的文件作为输入；启用 --experimental-wasm-modules 后，也接受扩展名为 .wasm 的文件。

选项

[历史]

版本	变更
v10.12.0	除了 V8 选项外，现在 Node.js 选项也允许使用下划线代替短横线。

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

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

`-`

新增于：v8.0.0

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

`--`

新增于：v6.11.0

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

`--abort-on-uncaught-exception`

新增于：v0.10.8

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

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

`--allow-addons`

新增于：v21.6.0, v20.12.0

[稳定版：1 - 实验性]

稳定版：1 稳定性：1。1 - 主动开发

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

示例：

// 尝试 require 一个原生插件
require('nodejs-addon-example')

bash

$ 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'
}

`--allow-child-process`

新增于：v20.0.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.1 - 活跃开发中

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

示例：

const childProcess = require('node:child_process')
// 尝试绕过权限
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")'])

bash

$ 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 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'
}

`--allow-fs-read`

[历史]

版本	变更
v23.5.0	权限模型和 --allow-fs 标志已稳定。
v20.7.0	不再允许以逗号 (`,`) 分隔的路径。
v20.0.0	在 v20.0.0 中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定。

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

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

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

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

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

bash

$ 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'
}

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

bash

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

`--allow-fs-write`

[历史]

版本	变更
v23.5.0	权限模型和 --allow-fs 标志稳定。
v20.7.0	不再允许以逗号 (`,`) 分隔的路径。
v20.0.0	在 v20.0.0 中添加

[稳定: 2 - 稳定]

稳定: 2 稳定性: 2 - 稳定。

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

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

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

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

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

`--allow-wasi`

在 v22.3.0、v20.16.0 中添加

[稳定: 1 - 实验性]

稳定: 1 稳定性: 1.1 - 主动开发

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

示例：

const { WASI } = require('node:wasi')
// 尝试绕过权限
new WASI({
  version: 'preview1',
  // 尝试挂载整个文件系统
  preopens: {
    '/': '/',
  },
})

bash

$ 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',
}

`--allow-worker`

新增于：v20.0.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 主动开发中

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

示例：

const { Worker } = require('node:worker_threads')
// 尝试绕过权限
new Worker(__filename)

bash

$ 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'
}

`--build-snapshot`

新增于：v18.8.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

bash

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

# 运行 snapshot.js 初始化应用程序并将它的状态快照到 snapshot.blob。 {#run-snapshotjs-to-initialize-the-application-and-snapshot-the}
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

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

# 加载生成的快照并从 index.js 启动应用程序。 {#state-of-it-into-snapshotblob}
$ node --snapshot-blob snapshot.blob index.js
I am from the snapshot

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

bash

$ 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

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

目前，运行时快照的支持处于实验阶段，原因是：

`--build-snapshot-config`

新增于: v21.6.0, v20.12.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

当前支持以下选项：

builder <字符串> 必需。提供在构建快照之前执行的脚本名称，如同使用 builder 作为主脚本名称传递了 --build-snapshot 一样。
withoutCodeCache <布尔值> 可选。包含代码缓存减少了编译快照中包含的函数所花费的时间，但代价是快照尺寸更大，并可能破坏快照的可移植性。

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

`-c`, `--check`

[历史]

版本	变更
v10.0.0	现在支持在检查文件时使用 `--require` 选项。
v5.0.0, v4.2.0	新增于：v5.0.0, v4.2.0

无需执行即可语法检查脚本。

`--completion-bash`

新增于：v10.12.0

打印 Node.js 可使用的 bash 自动补全脚本。

bash

node --completion-bash > node_bash_completion
source node_bash_completion

`-C condition`, `--conditions=condition`

[历史]

版本	变更
v22.9.0, v20.18.0	此标志不再是实验性的。
v14.9.0, v12.19.0	新增于：v14.9.0, v12.19.0

[稳定：2 - 稳定]

稳定：2 稳定性：2 - 稳定

提供自定义的条件导出解析条件。

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

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

例如，要使用 "development" 解析运行模块：

bash

node -C development app.js

`--cpu-prof`

[历史]

版本	变更
v22.4.0, v20.16.0	`--cpu-prof` 标记现已稳定。
v12.0.0	在 v12.0.0 中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

启动时启动 V8 CPU 分析器，并在退出前将 CPU 配置文件写入磁盘。

如果未指定 --cpu-prof-dir，则生成的配置文件将放置在当前工作目录中。

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

bash

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

`--cpu-prof-dir`

[历史]

版本	变更
v22.4.0, v20.16.0	`--cpu-prof` 标记现已稳定。
v12.0.0	在 v12.0.0 中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

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

`--cpu-prof-interval`

[历史]

版本	变更
v22.4.0, v20.16.0	`--cpu-prof` 标记现已稳定。
v12.2.0	v12.2.0 版本中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

`--cpu-prof-name`

[历史]

版本	变更
v22.4.0, v20.16.0	`--cpu-prof` 标记现已稳定。
v12.0.0	v12.0.0 版本中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

`--diagnostic-dir=directory`

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

影响以下选项的默认输出目录：

`--disable-proto=mode`

新增于：v13.12.0, v12.17.0

禁用 Object.prototype.__proto__ 属性。如果 mode 为 delete，则该属性将被完全删除。如果 mode 为 throw，则访问该属性将抛出一个代码为 ERR_PROTO_ACCESS 的异常。

`--disable-warning=code-or-type`

[稳定版: 1 - 实验版]

稳定版: 1 稳定性: 1.1 -活跃开发中

新增于：v21.3.0, v20.11.0

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

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

弃用警告列表。

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

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

ESMCJS

import sys from 'node:sys'

const sys = require('node:sys')

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

ESMCJS

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

vm.measureMemory()

const sys = require('node:sys')
const vm = require('node:vm')

vm.measureMemory()

`--disable-wasm-trap-handler`

新增于：v22.2.0, v20.15.0

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

bash

$ 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

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

`--disallow-code-generation-from-strings`

新增于: v9.8.0

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

`--dns-result-order=order`

[历史]

版本	变更
v22.1.0, v20.13.0	现在支持 `ipv6first`。
v17.0.0	默认值更改为 `verbatim`。
v16.4.0, v14.18.0	新增于: v16.4.0, v14.18.0

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

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

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

`--enable-fips`

新增于: v6.0.0

在启动时启用符合 FIPS 的加密。（需要使用符合 FIPS 的 OpenSSL 构建 Node.js。）

`--enable-network-family-autoselection`

新增于：v18.18.0

除非连接选项显式禁用，否则启用网络族自动选择算法。

`--enable-source-maps`

[历史]

版本	变更
v15.11.0, v14.18.0	此 API 不再是实验性的。
v12.12.0	新增于：v12.12.0

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

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

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

const originalPrepareStackTrace = Error.prepareStackTrace
Error.prepareStackTrace = (error, trace) => {
  // 修改错误和跟踪，并使用原始 Error.prepareStackTrace 格式化堆栈跟踪。
  return originalPrepareStackTrace(error, trace)
}

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

`--entry-url`

新增于: v23.0.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

遵循 ECMAScript 模块解析规则。

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

bash

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

`--env-file-if-exists=config`

新增于: v22.9.0

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

`--env-file=config`

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1.1 - 主动开发

[历史]

版本	变更
v21.7.0, v20.12.0	添加对多行值的支持。
v20.6.0	新增于: v20.6.0

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

您可以传递多个 --env-file 参数。后续文件会覆盖先前文件中定义的预先存在的变量。

如果文件不存在，则会抛出错误。

bash

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

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

text

PORT=3000

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

text

# 这是一个注释 {#--env-file=config}
PORT=3000 # 这也是一个注释

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

text

USERNAME="nodejs" # 结果值为 `nodejs`。

支持多行值：

text

MULTI_LINE="THIS IS
A MULTILINE"
# 结果值为 `THIS IS\nA MULTILINE`。 {#this-is-a-comment}

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

text

export USERNAME="nodejs" # 结果值为 `nodejs`。

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

`-e`, `--eval "脚本"` {#will-result-in-this-is\na-multiline-as-the-value}

[历史]

版本	变更
v22.6.0	eval 现在支持实验性的类型去除。
v5.11.0	内置库现在可用作预定义变量。
v0.5.2	在 v0.5.2 中添加

将以下参数作为 JavaScript 代码进行评估。REPL 中预定义的模块也可以在 脚本 中使用。

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

可以通过传递 --experimental-strip-types 来运行包含内联类型的代码。

`--experimental-async-context-frame`

在 v22.7.0 中添加

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

启用使用由 AsyncContextFrame 支持的 AsyncLocalStorage，而不是依赖于 async_hooks 的默认实现。这个新模型的实现方式非常不同，因此上下文数据在应用程序中的流动方式可能会有所不同。因此，目前建议在生产环境中使用它之前，确保您的应用程序行为不受此更改的影响。

`--experimental-eventsource`

新增于：v22.3.0, v20.18.0

启用在全局作用域上公开 EventSource Web API。

`--experimental-import-meta-resolve`

[历史]

版本	变更
v20.6.0, v18.19.0	默认情况下启用同步 `import.meta.resolve`，保留该标志用于启用以前支持的实验性第二个参数。
v13.9.0, v12.16.2	新增于：v13.9.0, v12.16.2

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

之前会限制整个 import.meta.resolve 功能。

`--experimental-loader=module`

[历史]

版本	变更
v12.11.1	此标志已从 `--loader` 重命名为 `--experimental-loader`。
v8.8.0	新增于：v8.8.0

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

`--experimental-network-inspection`

新增于：v22.6.0, v20.18.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

`--experimental-print-required-tla`

新增于：v22.0.0, v20.17.0

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

`--experimental-require-module`

[历史]

版本	变更
v23.0.0	此功能现在默认启用。
v22.0.0, v20.17.0	新增于：v22.0.0, v20.17.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.1 - 主动开发

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

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

`--experimental-sea-config`

新增于：v20.0.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

`--experimental-shadow-realm`

新增于：v19.0.0, v18.13.0

使用此标志启用ShadowRealm 支持。

`--experimental-strip-types`

新增于：v22.6.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.1 - 主动开发

启用 TypeScript 文件的实验性类型去除。有关更多信息，请参阅TypeScript 类型去除文档。

`--experimental-test-coverage`

[历史]

版本	变更
v20.1.0, v18.17.0	此选项可与 `--test` 一起使用。
v19.7.0, v18.15.0	v19.7.0, v18.15.0 版本中添加

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

`--experimental-test-isolation=mode`

v22.8.0 版本中添加

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.0 - 早期开发

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

`--experimental-test-module-mocks`

新增于：v22.3.0, v20.18.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.0 - 早期开发

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

`--experimental-transform-types`

新增于：v22.7.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.1 - 主动开发

启用将仅 TypeScript 语法转换为 JavaScript 代码。隐含 --experimental-strip-types 和 --enable-source-maps。

`--experimental-vm-modules`

新增于：v9.6.0

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

`--experimental-wasi-unstable-preview1`

[历史]

版本	变更
v20.0.0, v18.17.0	此选项不再需要，因为 WASI 已默认启用，但仍可以传递。
v13.6.0	从 `--experimental-wasi-unstable-preview0` 更改为 `--experimental-wasi-unstable-preview1`。
v13.3.0, v12.16.0	新增于：v13.3.0, v12.16.0

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

`--experimental-wasm-modules`

新增于：v12.3.0

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

`--experimental-webstorage`

新增于：v22.4.0

启用实验性的 Web Storage 支持。

`--expose-gc`

新增于：v22.3.0, v20.18.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性。此标志继承自 V8，并且可能会在 V8 上游发生更改。

此标志将公开来自 V8 的 gc 扩展。

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

`--force-context-aware`

新增于：v12.12.0

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

`--force-fips`

新增于：v6.0.0

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

`--force-node-api-uncaught-exceptions-policy`

新增于：v18.3.0, v16.17.0

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

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

`--frozen-intrinsics`

新增于: v11.12.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

仅支持根上下文。无法保证 globalThis.Array 确实是默认的内建对象引用。在此标志下，代码可能会中断。

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

`--heap-prof`

[历史]

版本	变更
v22.4.0, v20.16.0	`--heap-prof` 标志现在已稳定。
v12.4.0	新增于: v12.4.0

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

在启动时启动 V8 堆分析器，并在退出之前将堆配置文件写入磁盘。

如果未指定 --heap-prof-dir，则生成的配置文件将放置在当前工作目录中。

如果未指定 --heap-prof-name，则生成的配置文件将命名为 Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile。

bash

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

`--heap-prof-dir`

[历史]

版本	变更
v22.4.0, v20.16.0	`--heap-prof` 标志现在已稳定。
v12.4.0	v12.4.0 版本中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

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

`--heap-prof-interval`

[历史]

版本	变更
v22.4.0, v20.16.0	`--heap-prof` 标志现在已稳定。
v12.4.0	v12.4.0 版本中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

`--heap-prof-name`

[历史]

版本	变更
v22.4.0, v20.16.0	`--heap-prof` 标志现在已稳定。
v12.4.0	v12.4.0 版本中添加

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

`--heapsnapshot-near-heap-limit=max_count`

新增于：v15.1.0, v14.18.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

当 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 堆内存开销，并尽最大努力避免用尽进程可用的所有内存。当进程使用的内存超过系统认为合适的内存时，系统可能会根据系统配置突然终止进程。

bash

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

<--- Last few GCs --->

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


<--- JS stacktrace --->

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

`--heapsnapshot-signal=signal`

新增于：v12.0.0

启用信号处理器，当接收到指定的信号时，该处理器将导致 Node.js 进程写入堆转储。signal 必须是一个有效的信号名称。默认情况下禁用。

bash

$ 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

`-h`, `--help`

新增于：v0.1.3

打印 Node 命令行选项。此选项的输出比本文档的输出详细程度低。

`--icu-data-dir=file`

新增于：v0.11.15

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

`--import=module`

新增于：v19.0.0, v18.18.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

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

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

`--input-type=type`

新增于：v12.0.0

此配置项用于指示 Node.js 将 --eval 或 STDIN 输入解释为 CommonJS 模块还是 ES 模块。有效值为 "commonjs" 或 "module"。默认为 "commonjs"。

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

`--insecure-http-parser`

新增于：v13.4.0, v12.15.0, v10.19.0

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

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

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

以上所有情况都会使您的应用程序面临请求走私或投毒攻击的风险。避免使用此选项。

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

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

如果指定主机，请确保：

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

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

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

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

新增于：v7.6.0

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

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

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

新增于：v7.6.0

设置激活调试器时使用的 host:port。在发送 SIGUSR1 信号激活调试器时非常有用。

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

关于 host 参数用法的详细信息，请参见下面的安全警告。

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

指定调试器 WebSocket URL 的公开方式。

默认情况下，调试器 WebSocket URL 在 stderr 和 http://host:port/json/list 端点的 /json/list 下可用。

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

新增于：v22.2.0, v20.15.0

在 host:port 上激活调试器并等待调试器附加。默认 host:port 为 127.0.0.1:9229。如果指定端口 0，则将使用随机可用的端口。

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

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

新增于：v6.3.0

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

新增于：v0.7.7

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

`--jitless`

新增于：v12.0.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性。此标志继承自 V8，并可能发生上游更改。

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

`--localstorage-file=file`

新增于：v22.4.0

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

`--max-http-header-size=size`

[历史]

版本	变更
v13.13.0	将 HTTP 头的最大默认大小从 8 KiB 更改为 16 KiB。
v11.6.0, v10.15.0	新增于：v11.6.0, v10.15.0

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

`--napi-modules`

新增于：v7.10.0

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

`--network-family-autoselection-attempt-timeout`

新增于：v22.1.0, v20.13.0

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

`--no-addons`

新增于：v16.10.0, v14.19.0

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

`--no-deprecation`

新增于：v0.8.0

静默弃用警告。

`--no-experimental-detect-module`

[历史]

版本	变更
v22.7.0	语法检测默认启用。
v21.1.0, v20.10.0	新增于：v21.1.0, v20.10.0

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

`--no-experimental-global-navigator`

新增于：v21.2.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

`--no-experimental-repl-await`

新增于：v16.6.0

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

`--no-experimental-require-module`

[历史]

版本	变更
v23.0.0	默认情况下现在为 false。
v22.0.0, v20.17.0	添加于：v22.0.0, v20.17.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.1 - 活跃开发中

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

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

`--no-experimental-sqlite`

[历史]

版本	变更
v23.4.0	SQLite 已取消标记，但仍处于实验阶段。
v22.5.0	添加于：v22.5.0

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

`--no-experimental-websocket`

添加于：v22.0.0

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

`--no-extra-info-on-fatal-exception`

添加于：v17.0.0

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

`--no-force-async-hooks-checks`

新增于: v9.0.0

禁用 async_hooks 的运行时检查。当启用 async_hooks 时，这些检查仍将动态启用。

`--no-global-search-paths`

新增于: v16.10.0

不从全局路径（例如 $HOME/.node_modules 和 $NODE_PATH）搜索模块。

`--no-network-family-autoselection`

[历史]

版本	变更
v20.0.0	此标志已从 `--no-enable-network-family-autoselection` 重命名为 `--no-network-family-autoselection`。旧名称仍可用作别名。
v19.4.0	新增于: v19.4.0

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

`--no-warnings`

新增于: v6.0.0

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

`--node-memory-debug`

新增于: v15.0.0, v14.18.0

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

`--openssl-config=file`

新增于：v6.9.0

启动时加载 OpenSSL 配置文件。除其他用途外，如果 Node.js 是针对启用 FIPS 的 OpenSSL 构建的，则可以使用此选项启用符合 FIPS 的加密。

`--openssl-legacy-provider`

新增于：v17.0.0, v16.17.0

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

`--openssl-shared-config`

新增于：v18.5.0, v16.17.0, v14.21.0

启用 OpenSSL 默认配置段 openssl_conf，使其从 OpenSSL 配置文件读取。默认配置文件名为 openssl.cnf，但这可以通过环境变量 OPENSSL_CONF 或命令行选项 --openssl-config 来更改。默认 OpenSSL 配置文件的位置取决于 OpenSSL 与 Node.js 的链接方式。共享 OpenSSL 配置可能会产生不良影响，建议使用特定于 Node.js 的配置段 nodejs_conf，在不使用此选项时为默认配置。

`--pending-deprecation`

新增于：v8.0.0

发出待弃用警告。

待弃用警告通常与运行时弃用警告相同，但一个显著例外是它们默认情况下是关闭的，除非设置了--pending-deprecation命令行标志或NODE_PENDING_DEPRECATION=1环境变量，否则不会发出这些警告。待弃用警告用于提供一种可选的“早期警告”机制，开发人员可以利用它来检测已弃用的 API 使用情况。

`--permission`

[历史]

版本	变更
v23.5.0	权限模型现已稳定。
v20.0.0	新增于：v20.0.0

[稳定：2 - 稳定]

稳定：2 稳定性：2 - 稳定。

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

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

`--preserve-symlinks`

新增于: v6.3.0

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

默认情况下，当 Node.js 从符号链接到磁盘上不同位置的路径加载模块时，Node.js 将取消引用链接并使用模块的实际磁盘“真实路径”作为标识符和查找其他依赖模块的根路径。在大多数情况下，此默认行为是可以接受的。但是，当使用符号链接的同级依赖项时（如下例所示），如果 moduleA 尝试将 moduleB 作为同级依赖项引入，则默认行为会导致抛出异常：

text

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

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

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

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

`--preserve-symlinks-main`

新增于：v10.2.0

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

此标志的存在是为了使主模块能够选择与--preserve-symlinks给予所有其他导入的相同行为；但是，它们是单独的标志，以便与旧版本的 Node.js 向后兼容。

--preserve-symlinks-main并不意味着--preserve-symlinks；当在解析相对路径之前不希望遵循符号链接时，请同时使用--preserve-symlinks-main和--preserve-symlinks。

更多信息请参见--preserve-symlinks。

`-p`, `--print "script"`

[历史]

版本	变更
v5.11.0	内置库现在可作为预定义变量使用。
v0.6.4	新增于：v0.6.4

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

`--prof`

新增于：v2.0.0

生成 V8 性能分析器输出。

`--prof-process`

新增于：v5.2.0

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

`--redirect-warnings=file`

新增于：v8.0.0

将进程警告写入给定文件，而不是打印到标准错误流。如果文件不存在，则会创建该文件；如果文件存在，则会追加内容。如果尝试将警告写入文件时发生错误，则会将警告写入标准错误流。

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

`--report-compact`

新增于：v13.12.0, v12.17.0

以紧凑格式（单行 JSON）编写报告，比为人工阅读而设计的默认多行格式更易于日志处理系统使用。

`--report-dir=directory`, `report-directory=directory`

[历史]

版本	变更
v13.12.0, v12.17.0	此选项不再是实验性的。
v12.0.0	从 `--diagnostic-report-directory` 更改为 `--report-directory`。
v11.8.0	新增于：v11.8.0

报告生成的目录位置。

`--report-exclude-env`

新增于：v23.3.0

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

`--report-exclude-network`

新增于：v22.0.0, v20.13.0

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

`--report-filename=filename`

[历史记录]

版本	变更
v13.12.0, v12.17.0	此选项不再是实验性的。
v12.0.0	从 `--diagnostic-report-filename` 改为 `--report-filename`。
v11.8.0	新增于：v11.8.0

报告将写入的文件名。

如果文件名设置为 'stdout' 或 'stderr'，则报告将分别写入进程的标准输出或标准错误输出。

`--report-on-fatalerror`

[历史记录]

版本	变更
v14.0.0, v13.14.0, v12.17.0	此选项不再是实验性的。
v12.0.0	从 `--diagnostic-report-on-fatalerror` 改为 `--report-on-fatalerror`。
v11.8.0	新增于：v11.8.0

启用在致命错误（Node.js 运行时中的内部错误，例如内存不足）导致应用程序终止时触发报告。这有助于检查各种诊断数据元素，例如堆、堆栈、事件循环状态、资源消耗等，以分析致命错误的原因。

`--report-on-signal`

[历史]

版本	变更
v13.12.0, v12.17.0	此选项不再是实验性的。
v12.0.0	从 `--diagnostic-report-on-signal` 改为 `--report-on-signal`。
v11.8.0	在 v11.8.0 中添加

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

`--report-signal=signal`

[历史]

版本	变更
v13.12.0, v12.17.0	此选项不再是实验性的。
v12.0.0	从 `--diagnostic-report-signal` 改为 `--report-signal`。
v11.8.0	在 v11.8.0 中添加

设置或重置报告生成的信号（Windows 上不支持）。默认信号为 SIGUSR2。

`--report-uncaught-exception`

[历史]

版本	变更
v18.8.0, v16.18.0	如果已处理未捕获的异常，则不会生成报告。
v13.12.0, v12.17.0	此选项不再是实验性的。
v12.0.0	从 `--diagnostic-report-uncaught-exception` 改为 `--report-uncaught-exception`。
v11.8.0	在 v11.8.0 中添加

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

`-r`, `--require module`

新增于: v1.6.0

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

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

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

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

`--run`

[历史]

版本	变更
v22.3.0	添加了 `NODE_RUN_SCRIPT_NAME` 环境变量。
v22.3.0	添加了 `NODE_RUN_PACKAGE_JSON_PATH` 环境变量。
v22.3.0	遍历到根目录并查找 `package.json` 文件以从中运行命令，并相应地更新 `PATH` 环境变量。
v22.0.0	新增于: v22.0.0

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

这将运行 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 脚本：

bash

$ node --run test

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

bash

$ node --run test -- --verbose

有意限制

node --run 并非旨在与 npm run 或其他包管理器的 run 命令的行为匹配。Node.js 的实现有意地更加受限，以便专注于最常见用例的最高性能。其他 run 实现中的一些有意排除的功能包括：

除了指定的脚本之外，运行 pre 或 post 脚本。
定义包管理器特定的环境变量。

环境变量

使用 --run 运行脚本时，将设置以下环境变量：

NODE_RUN_SCRIPT_NAME：正在运行的脚本的名称。例如，如果使用 --run 运行 test，则此变量的值将为 test。
NODE_RUN_PACKAGE_JSON_PATH：正在处理的 package.json 的路径。

`--secure-heap-min=n`

新增于：v15.6.0

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

`--secure-heap=n`

新增于: v15.6.0

初始化一个 n 字节的 OpenSSL 安全堆。初始化后，在密钥生成和其他操作期间，OpenSSL 内部选择的内存分配类型将使用安全堆。例如，这对于防止由于指针越界而导致敏感信息泄露非常有用。

安全堆大小固定，运行时无法调整大小，因此，如果使用安全堆，务必选择足够大的堆来覆盖所有应用程序的使用。

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

安全堆默认情况下是禁用的。

安全堆在 Windows 上不可用。

更多详情请参见 CRYPTO_secure_malloc_init。

`--snapshot-blob=path`

新增于: v18.8.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

在不使用 --build-snapshot 的情况下，--snapshot-blob 指定用于恢复应用程序状态的 blob 的路径。

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

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

`--test`

[历史]

版本	变更
v20.0.0	测试运行器现已稳定。
v19.2.0, v18.13.0	测试运行器现在支持在监视模式下运行。
v18.1.0, v16.17.0	新增于：v18.1.0, v16.17.0

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

`--test-concurrency`

新增于：v21.0.0, v20.10.0, v18.19.0

测试运行器 CLI 将同时执行的最大测试文件数。如果 --experimental-test-isolation 设置为 'none'，则忽略此标志，并发数为 1。否则，并发数默认为 os.availableParallelism() - 1。

`--test-coverage-branches=threshold`

新增于：v22.8.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

`--test-coverage-exclude`

新增于：v22.5.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

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

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

`--test-coverage-functions=threshold`

新增于：v22.8.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

`--test-coverage-include`

新增于：v22.5.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

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

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

`--test-coverage-lines=threshold`

新增于：v22.8.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

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

`--test-force-exit`

新增于：v22.0.0, v20.14.0

配置测试运行程序，以便在所有已知测试执行完毕后退出进程，即使事件循环仍然处于活动状态。

`--test-name-pattern`

[历史]

版本	变更
v20.0.0	测试运行器现已稳定。
v18.11.0	在 v18.11.0 中添加

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

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

`--test-only`

[历史]

版本	变更
v20.0.0	测试运行器现已稳定。
v18.0.0, v16.17.0	在 v18.0.0, v16.17.0 中添加

配置测试运行器，使其仅执行设置了 only 选项的顶级测试。禁用测试隔离时，不需要此标志。

`--test-reporter`

[历史]

版本	变更
v20.0.0	测试运行器现已稳定。
v19.6.0, v18.15.0	在 v19.6.0, v18.15.0 中添加

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

`--test-reporter-destination`

[历史]

版本	变更
v20.0.0	测试运行器现已稳定。
v19.6.0, v18.15.0	新增于：v19.6.0, v18.15.0

对应测试报告的目标位置。更多详情请参见关于测试报告的文档。

`--test-shard`

新增于：v20.5.0, v18.19.0

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

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

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

bash

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

`--test-skip-pattern`

新增于：v22.1.0

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

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

`--test-timeout`

新增于：v21.2.0, v20.11.0

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

`--test-update-snapshots`

[历史]

版本	变更
v23.4.0	快照测试不再是实验性功能。
v22.3.0	新增于：v22.3.0

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

`--throw-deprecation`

新增于：v0.11.14

针对弃用内容抛出错误。

`--title=title`

新增于：v10.7.0

在启动时设置 process.title。

`--tls-cipher-list=list`

新增于：v4.0.0

指定备用的默认 TLS 密码列表。需要 Node.js 构建时包含加密支持（默认）。

`--tls-keylog=file`

新增于：v13.2.0, v12.16.0

将 TLS 密钥材料记录到文件中。密钥材料采用 NSS SSLKEYLOGFILE 格式，可被软件（例如 Wireshark）用于解密 TLS 流量。

`--tls-max-v1.2`

新增于：v12.0.0, v10.20.0

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

`--tls-max-v1.3`

新增于：v12.0.0

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

`--tls-min-v1.0`

新增于：v12.0.0, v10.20.0

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

`--tls-min-v1.1`

新增于：v12.0.0, v10.20.0

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

`--tls-min-v1.2`

新增于：v12.2.0, v10.20.0

将默认 tls.DEFAULT_MIN_VERSION 设置为 'TLSv1.2'。这是 12.x 及更高版本的默认值，但此选项是为了与旧版 Node.js 版本兼容而提供的。

`--tls-min-v1.3`

新增于：v12.0.0

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

`--trace-deprecation`

新增于: v0.8.0

打印弃用函数的堆栈跟踪。

`--trace-env`

新增于: v23.4.0

将当前 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`

新增于: v23.4.0

除了 --trace-env 的功能外，此选项还会打印访问操作的 JavaScript 堆栈跟踪。

`--trace-env-native-stack`

新增于：v23.4.0

除了 --trace-env 的功能外，此选项还会打印访问的原生堆栈跟踪。

`--trace-event-categories`

新增于：v7.7.0

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

`--trace-event-file-pattern`

新增于：v9.8.0

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

`--trace-events-enabled`

新增于：v7.7.0

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

`--trace-exit`

新增于：v13.5.0, v12.16.0

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

`--trace-require-module=mode`

新增于：v23.5.0

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

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

`--trace-sigint`

新增于：v13.9.0, v12.17.0

在收到 SIGINT 信号时打印堆栈跟踪。

`--trace-sync-io`

新增于：v2.1.0

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

`--trace-tls`

新增于：v12.2.0

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

`--trace-uncaught`

新增于：v13.1.0

打印未捕获异常的堆栈跟踪；通常，会打印与创建 Error 对象相关的堆栈跟踪，而此选项使 Node.js 还会打印与抛出该值（不必是 Error 实例）相关的堆栈跟踪。

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

`--trace-warnings`

新增于：v6.0.0

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

`--track-heap-objects`

新增于：v2.4.0

跟踪堆对象分配以进行堆快照。

`--unhandled-rejections=mode`

[历史记录]

版本	变更
v15.0.0	将默认模式更改为 `throw`。之前，会发出警告。
v12.0.0, v10.17.0	新增于：v12.0.0, v10.17.0

使用此标志可以更改发生未处理的拒绝时应执行的操作。可以选择以下模式之一：

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

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

`--use-bundled-ca`, `--use-openssl-ca`

新增于：v6.11.0

使用当前 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`

新增于：v13.6.0, v12.17.0

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

以下值对 mode 有效：

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

`--v8-options`

新增于: v0.1.3

打印 V8 命令行选项。

`--v8-pool-size=num`

新增于: v5.10.0

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

如果设置为 0，则 Node.js 将根据对并行处理量估算值选择合适的线程池大小。

并行处理量指的是在给定机器上可以同时执行的计算数量。通常情况下，它与 CPU 数量相同，但在虚拟机或容器等环境中可能会有所不同。

`-v`, `--version`

新增于: v0.1.3

打印 Node.js 的版本。

`--watch`

[历史]

版本	变更
v22.0.0, v20.13.0	观察模式现已稳定。
v19.2.0, v18.13.0	测试运行器现在支持在观察模式下运行。
v18.11.0, v16.19.0	新增于: v18.11.0, v16.19.0

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

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

bash

node --watch index.js

`--watch-path`

[历史]

版本	变更
v22.0.0, v20.13.0	观察模式现已稳定。
v18.11.0, v16.19.0	新增于：v18.11.0, v16.19.0

[稳定性: 2 - 稳定]

稳定性: 2 稳定性: 2 - 稳定

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

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

bash

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

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

`--watch-preserve-output`

新增于：v19.3.0, v18.13.0

在观察模式重启进程时，禁用清除控制台。

bash

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

`--zero-fill-buffers`

新增于：v6.0.0

自动将所有新分配的 Buffer 和 SlowBuffer 实例清零。

环境变量

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

新增于：v22.1.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1。1 - 活跃开发

为 Node.js 实例启用模块编译缓存。详情请参阅模块编译缓存的文档。

`NODE_DEBUG=module[,…]`

新增于：v0.1.32

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

`NODE_DEBUG_NATIVE=module[,…]`

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

`NODE_DISABLE_COLORS=1`

新增于：v0.3.0

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

`NODE_DISABLE_COMPILE_CACHE=1`

新增于：v22.8.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1.1 - 活跃开发中

禁用 Node.js 实例的模块编译缓存。详情请参阅模块编译缓存的文档。

`NODE_EXTRA_CA_CERTS=file`

新增于：v7.3.0

设置后，已知的“根”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`

新增于：v0.11.15

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

`NODE_NO_WARNINGS=1`

新增于：v6.11.0

设置为 1 时，将静默处理警告。

`NODE_OPTIONS=options...`

新增于：v8.0.0

一个以空格分隔的命令行选项列表。options... 在命令行选项之前解释，因此命令行选项将覆盖或组合 options... 中的任何内容。如果使用环境中不允许的选项（例如 -p 或脚本文件），Node.js 将退出并显示错误。

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

bash

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

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

bash

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

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

bash

NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
# 等效于： {#the-inspector-will-be-available-on-port-5555}
node --require "./a.js" --require "./b.js"

允许的 Node.js 选项列在以下列表中。如果选项同时支持 --XX 和 --no-XX 变体，则两者都支持，但列表中仅包含一个。

--allow-addons
--allow-child-process
--allow-fs-read
--allow-fs-write
--allow-wasi
--allow-worker
--conditions, -C
--diagnostic-dir
--disable-proto
--disable-warning
--disable-wasm-trap-handler
--dns-result-order
--enable-fips
--enable-network-family-autoselection
--enable-source-maps
--entry-url
--experimental-abortcontroller
--experimental-async-context-frame
--experimental-detect-module
--experimental-eventsource
--experimental-import-meta-resolve
--experimental-json-modules
--experimental-loader
--experimental-modules
--experimental-permission
--experimental-print-required-tla
--experimental-require-module
--experimental-shadow-realm
--experimental-specifier-resolution
--experimental-strip-types
--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-deprecation
--no-experimental-global-navigator
--no-experimental-repl-await
--no-experimental-sqlite
--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-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
--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[:…]`

新增于：v0.1.32

':' 分隔的目录列表，会添加到模块搜索路径的开头。

在 Windows 系统上，使用 ';' 分隔符。

`NODE_PENDING_DEPRECATION=1`

新增于：v8.0.0

设置为 1 时，会发出即将弃用的警告。

即将弃用的警告通常与运行时弃用警告相同，显著的例外是它们默认情况下是关闭的，除非设置 --pending-deprecation 命令行标志或 NODE_PENDING_DEPRECATION=1 环境变量，否则不会发出这些警告。即将弃用的警告用于提供一种可选的“早期警告”机制，开发人员可以利用它来检测已弃用的 API 使用情况。

`NODE_PENDING_PIPE_INSTANCES=instances`

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

`NODE_PRESERVE_SYMLINKS=1`

新增于：v7.1.0

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

`NODE_REDIRECT_WARNINGS=file`

新增于: v8.0.0

设置此变量后，进程警告将被输出到指定的文件，而不是打印到标准错误流 stderr。如果文件不存在，则会创建该文件；如果文件存在，则会追加内容。如果尝试将警告写入文件时发生错误，则警告将写入标准错误流 stderr。这等效于使用 --redirect-warnings=file 命令行标志。

`NODE_REPL_EXTERNAL_MODULE=file`

[历史记录]

版本	变更
v22.3.0, v20.16.0	移除嵌入器使用此环境变量与 kDisableNodeOptionsEnv 结合使用的可能性。
v13.0.0, v12.16.0	新增于: v13.0.0, v12.16.0

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

`NODE_REPL_HISTORY=file`

新增于: v3.0.0

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

`NODE_SKIP_PLATFORM_CHECK=value`

新增于: v14.5.0

如果 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 可以设置为空字符串，以防止传播。

`NO_COLOR=<any>`

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

代码覆盖率输出 {#no_color=<any>}

代码覆盖率作为顶级键 result 上的 ScriptCoverage 对象数组输出：

json

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

源映射缓存

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

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

source-map-cache 是一个对象，其键表示提取源映射的文件，其值包含原始源映射 URL（在键 url 中）、解析的 Source Map v3 信息（在键 data 中）以及源文件的行长度（在键 lineLengths 中）。

json

{
  "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]
    }
  }
}

`OPENSSL_CONF=file`

新增于：v6.11.0

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

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

`SSL_CERT_DIR=dir`

新增于：v7.7.0

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

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

`SSL_CERT_FILE=file`

新增于：v7.7.0

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

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

`TZ`

[历史]

版本	变更
v16.2.0	使用 `process.env.TZ =` 更改 `TZ` 变量也会更改 Windows 上的时间区域。
v13.0.0	使用 `process.env.TZ =` 更改 `TZ` 变量会更改 POSIX 系统上的时间区域。
v0.0.1	添加于：v0.0.1

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

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

bash

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

`UV_THREADPOOL_SIZE=size`

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

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

除文件监视器 API 和明确声明为同步的 API 外，所有 fs API
异步加密 API，例如 crypto.pbkdf2()、crypto.scrypt()、crypto.randomBytes()、crypto.randomFill()、crypto.generateKeyPair()
dns.lookup()
除明确声明为同步的 API 外，所有 zlib API

由于 libuv 的线程池大小固定，这意味着如果出于任何原因任何这些 API 耗时过长，则在 libuv 线程池中运行的其他（看似无关）API 将会性能下降。为了减轻这个问题，一个可能的解决方案是通过将 'UV_THREADPOOL_SIZE' 环境变量设置为大于 4（其当前默认值）的值来增加 libuv 线程池的大小。但是，不保证使用 process.env.UV_THREADPOOL_SIZE=size 在进程内部进行设置就能生效，因为线程池是在运行时初始化过程中创建的，这早于用户代码的运行。有关更多信息，请参阅libuv 线程池文档。

有用的 V8 选项

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

`--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)，为其他用途保留一些内存并避免交换。

bash

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

`--max-semi-space-size=SIZE` (以 MiB 为单位)

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

由于 V8 堆的年轻代大小是半空间大小的三倍（参见 V8 中的 YoungGenerationSizeFromSemiSpaceSize），因此半空间增加 1 MiB 会应用于三个单独的半空间中的每一个，并导致堆大小增加 3 MiB。吞吐量改进取决于你的工作负载（参见 #42511）。

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

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

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

bash

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

`--perf-basic-prof`

`--perf-basic-prof-only-functions`

`--perf-prof`

`--perf-prof-unwinding-info`

`--prof`

`--security-revert`

`--stack-trace-limit=limit`

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

bash

node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # 打印 12

命令行 API ​

概要 ​

程序入口点 ​

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

选项 ​

- ​

-- ​

--abort-on-uncaught-exception ​

--allow-addons ​

--allow-child-process ​

--allow-fs-read ​

--allow-fs-write ​

--allow-wasi ​

--allow-worker ​

--build-snapshot ​

--build-snapshot-config ​

-c, --check ​

--completion-bash ​

-C condition, --conditions=condition ​

--cpu-prof ​

--cpu-prof-dir ​

--cpu-prof-interval ​

--cpu-prof-name ​

--diagnostic-dir=directory ​

--disable-proto=mode ​

--disable-warning=code-or-type ​

--disable-wasm-trap-handler ​

--disallow-code-generation-from-strings ​

--dns-result-order=order ​

--enable-fips ​

--enable-network-family-autoselection ​

--enable-source-maps ​

--entry-url ​

--env-file-if-exists=config ​

--env-file=config ​

-e, --eval "脚本" {#will-result-in-this-is\na-multiline-as-the-value} ​

--experimental-async-context-frame ​

--experimental-eventsource ​

--experimental-import-meta-resolve ​

--experimental-loader=module ​

--experimental-network-inspection ​

--experimental-print-required-tla ​

--experimental-require-module ​

--experimental-sea-config ​

--experimental-shadow-realm ​

--experimental-strip-types ​

--experimental-test-coverage ​

--experimental-test-isolation=mode ​

--experimental-test-module-mocks ​

--experimental-transform-types ​

--experimental-vm-modules ​

--experimental-wasi-unstable-preview1 ​

--experimental-wasm-modules ​

--experimental-webstorage ​

--expose-gc ​

--force-context-aware ​

--force-fips ​

--force-node-api-uncaught-exceptions-policy ​

--frozen-intrinsics ​

--heap-prof ​

--heap-prof-dir ​

--heap-prof-interval ​

--heap-prof-name ​

--heapsnapshot-near-heap-limit=max_count ​

--heapsnapshot-signal=signal ​

-h, --help ​

--icu-data-dir=file ​

--import=module ​

--input-type=type ​

--insecure-http-parser ​

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

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

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

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

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

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

-i, --interactive ​

--jitless ​

--localstorage-file=file ​

--max-http-header-size=size ​

命令行 API

概要

程序入口点

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

选项

`-`

`--`

`--abort-on-uncaught-exception`

`--allow-addons`

`--allow-child-process`

`--allow-fs-read`

`--allow-fs-write`

`--allow-wasi`

`--allow-worker`

`--build-snapshot`

`--build-snapshot-config`

`-c`, `--check`

`--completion-bash`

`-C condition`, `--conditions=condition`

`--cpu-prof`

`--cpu-prof-dir`

`--cpu-prof-interval`

`--cpu-prof-name`

`--diagnostic-dir=directory`

`--disable-proto=mode`

`--disable-warning=code-or-type`

`--disable-wasm-trap-handler`

`--disallow-code-generation-from-strings`

`--dns-result-order=order`

`--enable-fips`

`--enable-network-family-autoselection`

`--enable-source-maps`

`--entry-url`

`--env-file-if-exists=config`

`--env-file=config`

`-e`, `--eval "脚本"` {#will-result-in-this-is\na-multiline-as-the-value}

`--experimental-async-context-frame`

`--experimental-eventsource`

`--experimental-import-meta-resolve`

`--experimental-loader=module`

`--experimental-network-inspection`

`--experimental-print-required-tla`

`--experimental-require-module`

`--experimental-sea-config`

`--experimental-shadow-realm`

`--experimental-strip-types`

`--experimental-test-coverage`

`--experimental-test-isolation=mode`

`--experimental-test-module-mocks`

`--experimental-transform-types`

`--experimental-vm-modules`

`--experimental-wasi-unstable-preview1`

`--experimental-wasm-modules`

`--experimental-webstorage`

`--expose-gc`

`--force-context-aware`

`--force-fips`

`--force-node-api-uncaught-exceptions-policy`

`--frozen-intrinsics`

`--heap-prof`

`--heap-prof-dir`

`--heap-prof-interval`

`--heap-prof-name`

`--heapsnapshot-near-heap-limit=max_count`

`--heapsnapshot-signal=signal`

`-h`, `--help`

`--icu-data-dir=file`

`--import=module`

`--input-type=type`

`--insecure-http-parser`

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

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

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

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

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

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

`-i`, `--interactive`

`--jitless`

`--localstorage-file=file`

`--max-http-header-size=size`