runFile(path[, options])

新增于: v26.9.0
  • path <string> | <Buffer> | <URL> 一个基准模块的路径。
  • options <Object>
    • env <Object> 子进程环境。属性值必须是字符串或 undefined。这会替代父环境，而不是扩展它。默认值： process.env 的快照。
    • execArgv <string[]> Node.js 子进程的命令行选项。这是替换继承的选项，而不是扩展它们。基准测试运行器的选项、位置参数以及选择其他执行模式的选项不允许使用。默认值： 从当前进程继承的兼容选项。
    • signal <AbortSignal> 在中止时终止子进程。
  • 返回：BenchmarksStream

在一个新的子进程中准确运行一个基准模块，并返回它的对象模式事件流。当调用 runFile() 时，相对路径 path 会从当前工作目录解析。path 不会被当作通配符处理。除非信号被中止或流在启动前被销毁，否则每次调用都会使用一个新的子进程。输入发现、排序、并发、重试和多文件调度仍然由调用方负责。

🌐 Runs exactly one benchmark module in a fresh child process and returns its object-mode event stream. A relative path is resolved from the current working directory when runFile() is called. path is not interpreted as a glob. Unless the signal is aborted or the stream is destroyed before startup, every call uses a new child. Input discovery, ordering, concurrency, retries, and multi-file scheduling remain the caller's responsibility.

当启用权限模型时，调用者必须对 path 拥有文件系统读取权限，并且有创建子进程的权限。

🌐 When the Permission Model is enabled, the caller must have file system read access to path and permission to create child processes.

记录使用先进的子进程序列化，保留支持的结构化值，例如 bigint 和错误。子进程写入 stdout 和 stderr 会变成 'bench:diagnostic' 记录。权限失败、模块加载错误、子进程异常退出或取消操作也会发出错误诊断，并生成一个终端 'bench:summary'，其 success 属性为 false；这些执行失败不会让流出错。如果模块评估在声明基准测试之后失败，这些声明仍会在失败的总结之前执行。

🌐 Records use advanced child process serialization, preserving supported structured values such as bigint and errors. Child writes to stdout and stderr become 'bench:diagnostic' records. A permission failure, module loading error, abnormal child exit, or cancellation also emits an error diagnostic and produces a terminal 'bench:summary' whose success property is false; these execution failures do not error the stream. If module evaluation fails after declaring benchmarks, those declarations still run before the unsuccessful summary.

env、有效的继承选项，以及明确提供的 execArgv 会在调用 runFile() 时被复制。运行器会移除 NODE_OPTIONS，替换与 IPC 相关的环境变量，并设置它自己的子上下文、运行身份和文件身份变量，这些会覆盖 env 中同名的属性。子 Node.js 选项要通过 execArgv 传递，而不是 NODE_OPTIONS。标准的 child_process 环境传播仍然适用，包括 NODE_V8_COVERAGE、权限模型选项以及必需的 z/OS 变量。在子进程启动前中止 signal 会生成一个 AbortError 诊断，而不会启动子进程。在执行过程中中止则会向子进程发送 SIGTERM，如果子进程没有退出，则会升级为 SIGKILL。销毁返回的流遵循相同的终止流程。