Node.js v18.7.0 文档


目录

CLI 命令行#

中英对照

Node.js 具有各种各样的命令行选项。 这些选项暴露了内置调试、多种执行脚本的方式、以及其他有用的运行时选项。

概要#

中英对照

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

程序入口点#

中英对照

程序入口点是类似说明符的字符串。 如果字符串不是绝对路径,则解析为当前工作目录的相对路径。 然后由 CommonJS 模块加载器解析该路径。 如果没有找到对应的文件,则抛出错误。

    ECMAScript 模块加载器入口点警告#

    中英对照

    当加载 ECMAScript 模块加载器加载程序入口点时,node 命令将仅接受使用 .js.mjs、或 .cjs 扩展名的文件作为输入;当启用 --experimental-wasm-modules 时,则使用 .wasm 扩展名。

    选项#

    中英对照

    所有选项,包括 V8 选项,都允许用破折号 (-) 或下划线 (_) 分隔单词。 例如,--pending-deprecation 等价于 --pending_deprecation

    -#

    中英对照

    标准输入的别名。 类似于在其他命令行工具中使用 -,这意味着脚本是从标准输入读取的,其余的选项将传给该脚本。

    --#

    中英对照

    指示 node 选项的结束。 将其余参数传给脚本。 如果在此之前没有提供脚本文件名或评估/打印脚本,则下一个参数用作脚本文件名。

    --abort-on-uncaught-exception#

    中英对照

    中止而不是退出会导致使用调试器(例如 lldbgdbmdb)生成用于事后分析的核心文件。

    --completion-bash#

    中英对照

    为 Node.js 打印可源代码的 bash 完成脚本。

    
    

    -C=condition, --conditions=condition#

    中英对照

    启用对自定义的条件导出解析条件的实验性支持。

    
    

    --cpu-prof#

    中英对照

    启动时开始 V8 CPU 分析器,并且在退出前将 CPU 分析文件写入磁盘。

    
    

    --cpu-prof-dir#

    中英对照

    指定放置 --cpu-prof 生成的 CPU 分析文件的目录

    --cpu-prof-interval#

    中英对照

    --cpu-prof 生成的 CPU 分析文件指定以微秒为单位的采样间隔。 默认为 1000 微秒。

    --cpu-prof-name#

    中英对照

    指定 --cpu-prof 生成的 CPU 分析文件的文件名。

    --diagnostic-dir=directory#

    中英对照

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

      --disable-proto=mode#

      中英对照

      禁用 Object.prototype.__proto__ 属性。 如果 modedelete,则该属性将被完全删除。 如果 modethrow,则访问该属性会使用代码 ERR_PROTO_ACCESS 抛出异常。

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

      中英对照

      使从字符串生成代码的 evalnew Function 等内置语言功能抛出异常。 这不会影响 Node.js node:vm 模块。

      --dns-result-order=order#

      中英对照

      dns.lookup()dnsPromises.lookup() 中设置 verbatim 的默认值。 该值可能是:

        --enable-fips#

        中英对照

        在启动时启用符合 FIPS 的加密。 (需要针对兼容 FIPS 的 OpenSSL 构建 Node.js。)

        --enable-source-maps#

        中英对照

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

        --experimental-global-customevent#

        中英对照

        在全局作用域内公开 CustomEvent Web API

        --experimental-global-webcrypto#

        中英对照

        在全局作用域内公开 Web 加密 API

        --experimental-import-meta-resolve#

        中英对照

        启用实验性 import.meta.resolve() 支持。

        --experimental-loader=module#

        中英对照

        指定自定义的实验的 ECMAScript 模块加载器modulemodule 可以是任何作为 import 说明符接受的字符串。

        --experimental-network-imports#

        中英对照

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

        --experimental-policy#

        中英对照

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

        --no-experimental-fetch#

        中英对照

        禁用对 Fetch API 的实验性支持。

        --no-experimental-repl-await#

        中英对照

        使用此标志在交互式解释器中禁用顶层等待。

        --experimental-specifier-resolution=mode#

        中英对照

        设置解析 ES 模块说明符的解析算法。 有效选项为 explicitnode

        --experimental-vm-modules#

        中英对照

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

        --experimental-wasi-unstable-preview1#

        中英对照

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

        --experimental-wasm-modules#

        中英对照

        启用实验性 WebAssembly 模块支持。

        --force-context-aware#

        中英对照

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

        --force-fips#

        中英对照

        在启动时强制执行符合 FIPS 的加密。 (不能从脚本代码中禁用。)(与 --enable-fips 要求相同。)

        --frozen-intrinsics#

        中英对照

        启用像 ArrayObject 这样的实验性冻结内在函数。

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

        中英对照

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

        --heapsnapshot-near-heap-limit=max_count#

        中英对照

        当 V8 堆使用量接近堆限制时,将 V8 堆快照写入磁盘。 count 应该是非负整数(在这种情况下,Node.js 将不超过 max_count 的快照写入磁盘)。

        
        

        --heapsnapshot-signal=signal#

        中英对照

        启用信号句柄,当接收到指定的信号时,它会导致 Node.js 进程写入堆转储。 signal 必须是有效的信号名称。 默认禁用。

        
        

        --heap-prof#

        中英对照

        在启动时开始 V8 堆分析器,并在退出前将堆分析器写入磁盘。

        
        

        --heap-prof-dir#

        中英对照

        指定 --heap-prof 生成的堆分析文件将被放置的目录。

        --heap-prof-interval#

        中英对照

        指定 --heap-prof 生成的堆分析文件的平均采样间隔(以字节为单位)。 默认为 512 * 1024 字节。

        --heap-prof-name#

        中英对照

        指定 --heap-prof 生成的堆分析文件的文件名。

        --icu-data-dir=file#

        中英对照

        指定 ICU 数据加载路径。 (覆盖 NODE_ICU_DATA。)

        --input-type=type#

        中英对照

        这将 Node.js 配置为将字符串输入解释为 CommonJS 或 ES 模块。 字符串输入是通过 --eval--printSTDIN 输入的。

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

        中英对照

        host:port 上激活检查器并在用户脚本开始时中断。 默认 host:port127.0.0.1:9229

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

        中英对照

        设置检查器激活时使用的 host:port。 在通过发送 SIGUSR1 信号激活检查器时很有用。

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

        中英对照

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

        注意:绑定检查器到公共的“IP:端口”组合是不安全的#

        中英对照

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

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

          中英对照

          指定检查器网络套接字网址的暴露方式。

          --insecure-http-parser#

          中英对照

          使用接受无效 HTTP 标头的不安全 HTTP 解析器。 这可能允许与不一致的 HTTP 实现的互操作性。 它还可能允许请求走私和其他依赖于接受无效标头的 HTTP 攻击。 避免使用此选项。

          --jitless#

          中英对照

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

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

          中英对照

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

          --napi-modules#

          中英对照

          此选项为空操作。 它是为了兼容性而保留的。

          --no-addons#

          中英对照

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

          --no-deprecation#

          中英对照

          静默弃用警告。

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

          中英对照

          静默所有进程警告(包括弃用的)。

          --node-memory-debug#

          中英对照

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

          --openssl-config=file#

          中英对照

          在启动时加载 OpenSSL 配置文件。 除其他用途外,如果 Node.js 是针对支持 FIPS 的 OpenSSL 构建的,则可用于启用符合 FIPS 的加密。

          --openssl-shared-config#

          中英对照

          启用 OpenSSL 默认配置部分,从 OpenSSL 配置文件中读取 openssl_conf。 默认配置文件名为 openssl.cnf,但可以使用环境变量 OPENSSL_CONF 或使用命令行选项 --openssl-config 进行更改。 默认 OpenSSL 配置文件的位置取决于 OpenSSL 如何链接到 Node.js。 共享 OpenSSL 配置可能会产生不必要的影响,建议使用特定于 Node.js 的配置部分,它是 nodejs_conf,并且在不使用此选项时是默认设置。

          --openssl-legacy-provider#

          中英对照

          启用 OpenSSL 3.0 旧版提供程序。 有关详细信息,请参阅 OSSL_PROVIDER-旧版

          --pending-deprecation#

          中英对照

          触发挂起的弃用警告。

          --policy-integrity=sri#

          中英对照

          如果策略不具有指定的完整性,则指示 Node.js 在运行任何代码之前出错。 它需要子资源完整性字符串作为参数。

          --preserve-symlinks#

          中英对照

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

          
          

          --preserve-symlinks-main#

          中英对照

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

          --prof#

          中英对照

          生成 V8 分析器输出。

          --prof-process#

          中英对照

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

          --redirect-warnings=file#

          中英对照

          将进程警告写入给定文件而不是打印到标准错误。 如果文件不存在则创建,如果存在则追加。 如果在尝试将警告写入文件时发生错误,则警告将改为写入标准错误。

          --report-compact#

          中英对照

          以紧凑的单行 JSON 格式编写报告,与专为人类使用而设计的默认多行格式相比,日志处理系统更易于使用。

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

          中英对照

          生成报告的位置。

          --report-filename=filename#

          中英对照

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

          --report-on-fatalerror#

          中英对照

          使报告能够在导致应用程序终止的致命错误(Node.js 运行时中的内部错误,例如内存不足)时触发。 用于检查各种诊断数据元素,例如堆、堆栈、事件循环状态、资源消耗等 推断致命错误。

          --report-on-signal#

          中英对照

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

          --report-signal=signal#

          中英对照

          设置或重置报告生成信号(Windows 不支持)。 默认信号为 SIGUSR2

          --report-uncaught-exception#

          中英对照

          启用对未捕获的异常生成报告。 在结合原生堆栈和其他运行时环境数据检查 JavaScript 堆栈时很有用。

          --secure-heap=n#

          中英对照

          初始化 n 个字节的 OpenSSL 安全堆。 当初始化时,安全堆用于密钥生成和其他操作期间 OpenSSL 中选定类型的分配。 这很有用,例如,防止敏感信息因指针溢出或不足而泄漏。

          --secure-heap-min=n#

          中英对照

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

          --test#

          中英对照

          启动 Node.js 命令行测试运行器。 此标志不能与 --check--eval--interactive 或检查器组合。 请参阅从命令行运行测试了解更多详细信息。

          --test-only#

          中英对照

          将测试运行器配置为仅执行设置了 only 选项的顶层测试。

          --throw-deprecation#

          中英对照

          为弃用抛出错误。

          --title=title#

          中英对照

          在启动时设置 process.title

          --tls-cipher-list=list#

          中英对照

          指定替代的默认 TLS 密码列表。 需要使用加密支持构建 Node.js(默认)。

          --tls-keylog=file#

          中英对照

          将 TLS 密钥材料记录到文件中。 密钥材料为 NSS SSLKEYLOGFILE 格式,可被软件(如 Wireshark)用于解密 TLS 流量。

          --tls-max-v1.2#

          中英对照

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

          --tls-max-v1.3#

          中英对照

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

          --tls-min-v1.0#

          中英对照

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

          --tls-min-v1.1#

          中英对照

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

          --tls-min-v1.2#

          中英对照

          将默认的 tls.DEFAULT_MIN_VERSION 设置为 'TLSv1.2'。 这是 12.x 及更高版本的默认设置,但支持该选项是为了与较旧的 Node.js 版本兼容。

          --tls-min-v1.3#

          中英对照

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

          --trace-atomics-wait#

          中英对照

          Atomics.wait() 调用的简短摘要打印到标准错误。 输出可能如下所示:

          
          

            --trace-deprecation#

            中英对照

            打印弃用的堆栈跟踪。

            --trace-event-categories#

            中英对照

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

            --trace-event-file-pattern#

            中英对照

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

            --trace-events-enabled#

            中英对照

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

            --trace-exit#

            中英对照

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

            --trace-sigint#

            中英对照

            在 SIGINT 上打印堆栈跟踪。

            --trace-sync-io#

            中英对照

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

            --trace-tls#

            中英对照

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

            --trace-uncaught#

            中英对照

            打印未捕获异常的堆栈跟踪;通常,打印与创建 Error 相关的堆栈跟踪,而这使得 Node.js 也打印与抛出值相关的堆栈跟踪(不需要是 Error 实例)

            --trace-warnings#

            中英对照

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

            --track-heap-objects#

            中英对照

            跟踪堆快照的堆对象分配。

            --unhandled-rejections=mode#

            中英对照

            使用此标志可以改变发生未经处理的拒绝时应该发生的事情。 可以选择以下模式之一

              --use-bundled-ca, --use-openssl-ca#

              中英对照

              使用当前 Node.js 版本提供的捆绑 Mozilla CA 存储或使用 OpenSSL 的默认 CA 存储。 在构建时可以选择默认存储。

              --use-largepages=mode#

              中英对照

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

                --v8-options#

                中英对照

                打印 V8 命令行选项。

                --v8-pool-size=num#

                中英对照

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

                --zero-fill-buffers#

                中英对照

                自动零填充所有新分配的 BufferSlowBuffer 实例。

                -c, --check#

                中英对照

                语法检查脚本而不执行。

                -e, --eval "script"#

                中英对照

                将以下参数作为 JavaScript 评估。 交互式解释器中预定义的模块也可以在 script 中使用。

                -h, --help#

                中英对照

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

                -i, --interactive#

                中英对照

                即使标准输入似乎不是终端,也会打开交互式解释器。

                -p, --print "script"#

                中英对照

                -e 相同,但打印结果。

                -r, --require module#

                中英对照

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

                -v, --version#

                中英对照

                打印 node 的版本。

                环境变量#

                FORCE_COLOR=[1, 2, 3]#

                中英对照

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

                  NODE_DEBUG=module[,…]#

                  中英对照

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

                  NODE_DEBUG_NATIVE=module[,…]#

                  中英对照

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

                  NODE_DISABLE_COLORS=1#

                  中英对照

                  当设置时,颜色将不会在交互式解释器中使用。

                  NODE_EXTRA_CA_CERTS=file#

                  中英对照

                  当设置时,众所周知的 "root" CA(如 VeriSign)将使用 file 中的额外证书进行扩展。 该文件应包含一个或多个 PEM 格式的可信证书。 如果文件丢失或格式不正确,则将使用 process.emitWarning() 触发消息消息(一次),否则将忽略任何错误。

                  NODE_ICU_DATA=file#

                  中英对照

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

                  NODE_NO_WARNINGS=1#

                  中英对照

                  当设置为 1 时,则静默进程警告。

                  NODE_OPTIONS=options...#

                  中英对照

                  以空格分隔的命令行选项列表 options... 在命令行选项之前被解释,因此命令行选项将在 options... 中的任何内容之后覆盖或复合。如果使用了环境中不允许的选项,例如 -p 或脚本文件。

                  
                  

                  
                  

                  
                  

                      NODE_PATH=path[:…]#

                      中英对照

                      ':' 分隔的目录列表,以模块搜索路径为前缀。

                      NODE_PENDING_DEPRECATION=1#

                      中英对照

                      当设置为 1 时,触发挂起的弃用警告。

                      NODE_PENDING_PIPE_INSTANCES=instances#

                      中英对照

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

                      NODE_PRESERVE_SYMLINKS=1#

                      中英对照

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

                      NODE_REDIRECT_WARNINGS=file#

                      中英对照

                      当设置时,进程警告将触发到给定文件而不是打印到标准错误 如果文件不存在则创建,如果存在则追加。 如果在尝试将警告写入文件时发生错误,则警告将改为写入标准错误。 这相当于使用 --redirect-warnings=file 命令行标志。

                      NODE_REPL_HISTORY=file#

                      中英对照

                      用于存储持久的交互式解释器历史的文件路径。 默认路径是 ~/.node_repl_history,会被此变量覆盖。 将值设置为空字符串(''' ')会禁用持久的交互式解释器历史记录。

                      NODE_REPL_EXTERNAL_MODULE=file#

                      中英对照

                      Node.js 模块的路径,该模块将代替内置交互式解释器加载。 将此值覆盖为空字符串 ('') ,则将使用内置的交互式解释器。

                      NODE_SKIP_PLATFORM_CHECK=value#

                      中英对照

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

                      NODE_TLS_REJECT_UNAUTHORIZED=value#

                      中英对照

                      如果 value 等于 '0',则对 TLS 连接禁用证书验证。 这使得 TLS 和 HTTPS 不安全。 强烈建议不要使用此环境变量。

                      NODE_V8_COVERAGE=dir#

                      中英对照

                      当设置时,Node.js 将开始将 V8 JavaScript 代码覆盖源映射数据输出到作为参数提供的目录(覆盖信息以 JSON 格式写入带有 coverage 前缀的文件)。

                      覆盖范围的输出#

                      中英对照

                      覆盖输出为顶层键 result 上的 ScriptCoverage 对象数组:

                      
                      
                      源码映射的缓存#

                      中英对照

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

                      
                      

                      NO_COLOR=<any>#

                      中英对照

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

                      OPENSSL_CONF=file#

                      中英对照

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

                      SSL_CERT_DIR=dir#

                      中英对照

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

                      SSL_CERT_FILE=file#

                      中英对照

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

                      TZ#

                      中英对照

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

                      
                      

                      UV_THREADPOOL_SIZE=size#

                      中英对照

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

                        有用的 V8 选项#

                        中英对照

                        V8 有自己的一组命令行选项。 任何提供给 node 的 V8 命令行选项都将传给 V8 来处理。 V8 的选项没有稳定性保证。 V8 团队本身并不认为它们是其正式 API 的一部分,并保留随时更改它们的权利。 同样,它们也不在 Node.js 稳定性保证范围内。 许多 V8 选项只对 V8 开发者有用。 尽管如此,有一小组 V8 选项广泛适用于 Node.js,它们记录在此处:

                        --max-old-space-size=SIZE#

                        中英对照

                        设置 V8 旧内存部分的最大内存大小。 随着内存消耗接近极限,V8 会花更多的时间在垃圾回收上,以释放未使用的内存。

                        
                        

                        --max-semi-space-size=SIZE(以兆字节为单位)#

                        中英对照

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

                        返回顶部