运行时选项

概述

Node.js 运行时选项允许自定义 JavaScript 运行时环境的行为。这些选项控制 Node.js 执行的各个方面，包括调试功能、模块加载行为、安全功能和性能设置。

选项语法

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

Node.js 中的选项允许使用连字符（-）或下划线（_）分隔单词。例如，--pending-deprecation 和 --pending_deprecation 都是有效的。如果一个带值的选项被传递多次，则使用最后一次传递的值。

来源：doc/api/cli.md64-74

选项类别

Node.js 运行时选项根据其目的和范围分为几个类别

来源：src/node_options.h44-375 src/node_options.cc312-636

Node.js 选项与 V8 选项

Node.js 拥有自己的一组选项（node [options]），以及直接传递给 V8 JavaScript 引擎的选项（[V8 options]）。您可以通过运行 node --v8-options 来查看所有可用的 V8 选项。

来源：doc/api/cli.md18 doc/node.148-49

选项处理流程

下图说明了 Node.js 如何处理命令行选项

来源：src/node_options.cc290-308 doc/api/cli.md72-74

关键运行时选项

调试和内省选项

这些选项控制调试和内省功能

选项	描述
`--inspect[=[host:]port]`	在 host:port 上启用内省器（默认为 127.0.0.1:9229）
`--inspect-brk[=[host:]port]`	启用内省器并在用户脚本的开头中断
`--inspect-wait`	等待调试器连接后再开始执行
`--inspect-publish-uid=stderr,http`	指定内省 UUID 的发布位置

来源：src/node_options.cc314-359 doc/api/cli.md96-127

模块系统选项

这些选项会影响模块的加载和执行方式

选项	描述
`--input-type=type`	指定字符串输入的输入类型（commonjs、module、commonjs-typescript、module-typescript）
`--conditions=conditions`	用于条件导出和导入的其他用户条件
`--experimental-import-meta-resolve`	启用实验性的 import.meta.resolve() 支持
`--experimental-loader=module`	使用指定的模块作为自定义加载器
`--experimental-wasm-modules`	启用实验性的 WebAssembly 模块支持

来源：src/node_options.cc363-484 doc/api/cli.md445-460

权限模型选项

这些选项用于启用和配置权限模型

选项	描述
`--permission`	启用权限系统
`--allow-fs-read=path`	允许对指定路径进行文件系统读取访问
`--allow-fs-write=path`	允许对指定路径进行文件系统写入访问
`--allow-addons`	当设置任何权限时，允许使用原生插件
`--allow-child-process`	当设置任何权限时，允许使用子进程
`--allow-worker`	当设置任何权限时，允许使用 worker 线程
`--allow-wasi`	当设置任何权限时，允许使用 WASI

来源：doc/api/cli.md119-190 src/node_options.cc485-513

性能分析选项

这些选项启用了各种性能分析功能

选项	描述
`--cpu-prof`	启动时开始 V8 CPU 分析器
`--cpu-prof-dir=dir`	输出 CPU 配置文件的目录
`--cpu-prof-name=name`	CPU 配置文件输出的文件名
`--cpu-prof-interval=microseconds`	CPU 配置文件的采样间隔（默认为 1000）
`--heap-prof`	启动时开始 V8 堆分析器
`--heap-prof-dir=dir`	输出堆配置文件的目录
`--heap-prof-name=name`	堆配置文件输出的文件名
`--heap-prof-interval=bytes`	堆配置文件的平均采样间隔（以字节为单位）（默认为 512 * 1024）

来源：doc/api/cli.md482-536 src/node_options.cc170-180

实验性功能选项

Node.js 包含许多实验性功能，可以通过特定标志启用

选项	描述
`--experimental-eventsource`	启用实验性 EventSource Web API
`--experimental-shadow-realm`	启用 ShadowRealm 支持
`--experimental-vm-modules`	在 VM 模块中启用实验性 ES 模块支持
`--experimental-webstorage`	启用实验性 Web Storage API
`--experimental-transform-types`	启用 TypeScript 专有语法的转换为 JavaScript 代码
`--experimental-test-module-mocks`	在测试运行器中启用模块模拟

来源：doc/api/cli.md429-461 src/node_options.cc429-444

选项实现

Node.js 的选项系统在几个内部类中实现

来源：src/node_options.h47-375 src/node_options.cc37-112

选项解析

选项使用与选项类相对应的专用解析器类进行解析

来源：src/node_options.cc244-268 src/node_options.cc379-443

选项验证

每类选项都有其在 CheckOptions 方法中实现的验证逻辑。这确保了选项之间相互兼容，并且对于当前的 Node.js 构建配置是有效的。

例如，验证可以防止不兼容的选项一起使用

--tls-min-v1.3 and --tls-max-v1.2 cannot be used together
--use-openssl-ca and --use-bundled-ca cannot be used together
--check and --eval cannot be used together

来源：src/node_options.cc76-112 src/node_options.cc111-239

全局运行时访问

一些运行时选项会在全局 process 对象上设置属性，从而可以从 JavaScript 中访问它们

命令行标志	Process 属性	值类型
`--eval`	`process._eval`	字符串
`--print`	`process._print_eval`	布尔值
`--check`	`process._syntax_check_only`	布尔值
`--interactive`	`process._forceRepl`	布尔值
`--require`	`process._preload_modules`	数组
`--no-deprecation`	`process.noDeprecation`	布尔值
`--no-warnings`	`process.noProcessWarnings`	布尔值
`--trace-warnings`	`process.traceProcessWarnings`	布尔值
`--throw-deprecation`	`process.throwDeprecation`	布尔值
`--trace-deprecation`	`process.traceDeprecation`	布尔值
`--inspect-brk`	`process._breakFirstLine`	布尔值
`--inspect-brk-node`	`process._breakNodeFirstLine`	布尔值

来源： lib/internal/process/pre_execution.js244-257 doc/api/globals.md623-643