Node.js v16.20.2 文档

类：vm.Script#

¥Class: vm.Script

vm.Script 类的实例包含可以在特定上下文中执行的预编译脚本。

¥Instances of the vm.Script class contain precompiled scripts that can be executed in specific contexts.

new vm.Script(code[, options])#

• code <string> 要编译的 JavaScript 代码。

  ¥code <string> The JavaScript code to compile.

• options <Object> | <string>

  • filename <string> 指定此脚本生成的堆栈跟踪中使用的文件名。默认值：'evalmachine.<anonymous>'。

    ¥filename <string> Specifies the filename used in stack traces produced by this script. Default: 'evalmachine.<anonymous>'.

  • lineOffset <number> 指定在此脚本生成的堆栈跟踪中显示的行号偏移量。默认值：0。

    ¥lineOffset <number> Specifies the line number offset that is displayed in stack traces produced by this script. Default: 0.

  • columnOffset <number> 指定在此脚本生成的堆栈跟踪中显示的第一行列号偏移量。默认值：0。

    ¥columnOffset <number> Specifies the first-line column number offset that is displayed in stack traces produced by this script. Default: 0.

  • cachedData <Buffer> | <TypedArray> | <DataView> 为所提供的源提供可选的 Buffer 或 TypedArray 或 DataView，其中包含 V8 的代码缓存数据。当提供时，cachedDataRejected 值将设置为 true 或 false，具体取决于 V8 对数据的接受程度。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source. When supplied, the cachedDataRejected value will be set to either true or false depending on acceptance of the data by V8.

  • produceCachedData <boolean> 当 true 且没有 cachedData 存在时，则 V8 将尝试为 code 生成代码缓存数据。当成功后，会生成带有 V8 代码缓存数据的 Buffer 并存储在返回的 vm.Script 实例的 cachedData 属性中。cachedDataProduced 值将设置为 true 或 false，这取决于代码缓存数据是否成功生成。此选项已弃用，取而代之的是 script.createCachedData()。默认值：false。

    ¥produceCachedData <boolean> When true and no cachedData is present, V8 will attempt to produce code cache data for code. Upon success, a Buffer with V8's code cache data will be produced and stored in the cachedData property of the returned vm.Script instance. The cachedDataProduced value will be set to either true or false depending on whether code cache data is produced successfully. This option is deprecated in favor of script.createCachedData(). Default: false.

  • importModuleDynamically <Function> 在调用 import() 时在评估此模块期间调用。如果未指定此选项，则调用 import() 将使用 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING 拒绝。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。

    ¥importModuleDynamically <Function> Called during evaluation of this module when import() is called. If this option is not specified, calls to import() will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. This option is part of the experimental modules API. We do not recommend using it in a production environment.

    • specifier <string> 说明符传递给 import()

      ¥specifier <string> specifier passed to import()

    • script <vm.Script>

    • importAssertions <Object> 传给 optionsExpression 可选参数的 "assert" 值，如果没有提供值，则为空对象。

      ¥importAssertions <Object> The "assert" value passed to the optionsExpression optional parameter, or an empty object if no value was provided.

    • 返回：<Module Namespace Object> | <vm.Module> 建议返回 vm.Module 以利用错误跟踪，并避免包含 then 函数导出的命名空间出现问题。

      ¥Returns: <Module Namespace Object> | <vm.Module> Returning a vm.Module is recommended in order to take advantage of error tracking, and to avoid issues with namespaces that contain then function exports.

如果 options 是字符串，则指定文件名。

¥If options is a string, then it specifies the filename.

创建新的 vm.Script 对象编译 code 但不运行它。编译后的 vm.Script 可以多次运行。code 没有绑定到任何全局对象；相反，它在每次运行之前绑定，仅针对该运行。

¥Creating a new vm.Script object compiles code but does not run it. The compiled vm.Script can be run later multiple times. The code is not bound to any global object; rather, it is bound before each run, just for that run.

script.cachedDataRejected#

• <boolean> | <undefined>

当提供 cachedData 来创建 vm.Script 时，该值将根据 V8 对数据的接受情况设置为 true 或 false。否则值为 undefined。

¥When cachedData is supplied to create the vm.Script, this value will be set to either true or false depending on acceptance of the data by V8. Otherwise the value is undefined.

script.createCachedData()#

• 返回：<Buffer>

  ¥Returns: <Buffer>

创建可与 Script 构造函数的 cachedData 选项一起使用的代码缓存。返回 Buffer。此方法可以随时调用任意次数。

¥Creates a code cache that can be used with the Script constructor's cachedData option. Returns a Buffer. This method may be called at any time and any number of times.

Script 的代码缓存不包含任何 JavaScript 可观察状态。代码缓存可以安全地与脚本源一起保存，并用于多次构造新的 Script 实例。

¥The code cache of the Script doesn't contain any JavaScript observable states. The code cache is safe to be saved along side the script source and used to construct new Script instances multiple times.

Script 源代码中的函数可以标记为延迟编译，并且在构建 Script 时不会编译它们。这些函数将在第一次调用时被编译。代码缓存序列化 V8 目前知道的关于 Script 的元数据，它可以用来加速未来的编译。

¥Functions in the Script source can be marked as lazily compiled and they are not compiled at construction of the Script. These functions are going to be compiled when they are invoked the first time. The code cache serializes the metadata that V8 currently knows about the Script that it can use to speed up future compilations.

const script = new vm.Script(`
function add(a, b) {
  return a + b;
}

const x = add(1, 2);
`);

const cacheWithoutAdd = script.createCachedData();
// In `cacheWithoutAdd` the function `add()` is marked for full compilation
// upon invocation.

script.runInThisContext();

const cacheWithAdd = script.createCachedData();
// `cacheWithAdd` contains fully compiled function `add()`. 拷贝

script.runInContext(contextifiedObject[, options])#

• contextifiedObject <Object> vm.createContext() 方法返回的 contextified 对象。

  ¥contextifiedObject <Object> A contextified object as returned by the vm.createContext() method.

• options <Object>

  • displayErrors <boolean> 当为 true 时，如果编译 code 时出现 Error，则导致错误的代码行会附加到堆栈跟踪中。默认值：true。

    ¥displayErrors <boolean> When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.

  • timeout <integer> 指定终止执行前执行 code 的毫秒数。如果执行终止，则将抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

• 返回：<any> 脚本中最后一条语句执行的结果。

  ¥Returns: <any> the result of the very last statement executed in the script.

在给定的 contextifiedObject 中运行 vm.Script 对象包含的编译代码并返回结果。运行代码无权访问本地作用域。

¥Runs the compiled code contained by the vm.Script object within the given contextifiedObject and returns the result. Running code does not have access to local scope.

下面的示例编译代码，增加一个全局变量，设置另一个全局变量的值，然后多次执行代码。全局变量包含在 context 对象中。

¥The following example compiles code that increments a global variable, sets the value of another global variable, then execute the code multiple times. The globals are contained in the context object.

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

const context = {
  animal: 'cat',
  count: 2
};

const script = new vm.Script('count += 1; name = "kitty";');

vm.createContext(context);
for (let i = 0; i < 10; ++i) {
  script.runInContext(context);
}

console.log(context);
// Prints: { animal: 'cat', count: 12, name: 'kitty' } 拷贝

使用 timeout 或 breakOnSigint 选项将导致新的事件循环和相应的线程被启动，其性能开销非零。

¥Using the timeout or breakOnSigint options will result in new event loops and corresponding threads being started, which have a non-zero performance overhead.

script.runInNewContext([contextObject[, options]])#

• contextObject <Object> 将成为 contextified 的对象。如果为 undefined，则将创建新的对象。

  ¥contextObject <Object> An object that will be contextified. If undefined, a new object will be created.

• options <Object>

  • displayErrors <boolean> 当为 true 时，如果编译 code 时出现 Error，则导致错误的代码行会附加到堆栈跟踪中。默认值：true。

    ¥displayErrors <boolean> When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.

  • timeout <integer> 指定终止执行前执行 code 的毫秒数。如果执行终止，则将抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

  • contextName <string> 新创建的上下文的可读名称。默认值：'VM Context i'，其中 i 是所创建上下文的升序数字索引。

    ¥contextName <string> Human-readable name of the newly created context. Default: 'VM Context i', where i is an ascending numerical index of the created context.

  • contextOrigin <string> 起源 对应于新创建的上下文，用于显示目的。来源的格式应该像 URL，但只有协议、主机和端口（如果需要），就像 URL 对象的 url.origin 属性的值。最值得注意的是，该字符串应省略尾部斜杠，因为它表示路径。默认值：''。

    ¥contextOrigin <string> Origin corresponding to the newly created context for display purposes. The origin should be formatted like a URL, but with only the scheme, host, and port (if necessary), like the value of the url.origin property of a URL object. Most notably, this string should omit the trailing slash, as that denotes a path. Default: ''.

  • contextCodeGeneration <Object>

    • strings <boolean> 如果设置为 false，则任何对 eval 或函数构造函数（Function、GeneratorFunction 等）的调用都将抛出 EvalError。默认值：true。

      ¥strings <boolean> If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) will throw an EvalError. Default: true.

    • wasm <boolean> 如果设置为 false，则任何编译 WebAssembly 模块的尝试都将抛出 WebAssembly.CompileError。默认值：true。

      ¥wasm <boolean> If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. Default: true.

  • microtaskMode <string> 如果设置为 afterEvaluate，微任务（通过 Promise 和 async function 安排的任务）将在脚本运行后立即运行。在这种情况下，它们包含在 timeout 和 breakOnSigint 范围内。

    ¥microtaskMode <string> If set to afterEvaluate, microtasks (tasks scheduled through Promises and async functions) will be run immediately after the script has run. They are included in the timeout and breakOnSigint scopes in that case.

• 返回：<any> 脚本中最后一条语句执行的结果。

  ¥Returns: <any> the result of the very last statement executed in the script.

首先对给定的 contextObject 进行上下文隔离化，在创建的上下文中运行 vm.Script 对象包含的编译代码，并返回结果。运行代码无权访问本地作用域。

¥First contextifies the given contextObject, runs the compiled code contained by the vm.Script object within the created context, and returns the result. Running code does not have access to local scope.

以下示例编译设置全局变量的代码，然后在不同的上下文中多次执行代码。全局变量设置并包含在每个单独的 context 中。

¥The following example compiles code that sets a global variable, then executes the code multiple times in different contexts. The globals are set on and contained within each individual context.

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

const script = new vm.Script('globalVar = "set"');

const contexts = [{}, {}, {}];
contexts.forEach((context) => {
  script.runInNewContext(context);
});

console.log(contexts);
// Prints: [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }] 拷贝

script.runInThisContext([options])#

• options <Object>

  • displayErrors <boolean> 当为 true 时，如果编译 code 时出现 Error，则导致错误的代码行会附加到堆栈跟踪中。默认值：true。

    ¥displayErrors <boolean> When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.

  • timeout <integer> 指定终止执行前执行 code 的毫秒数。如果执行终止，则将抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

• 返回：<any> 脚本中最后一条语句执行的结果。

  ¥Returns: <any> the result of the very last statement executed in the script.

在当前 global 对象的上下文中运行 vm.Script 包含的编译代码。运行代码无权访问局部作用域，但可以访问当前 global 对象。

¥Runs the compiled code contained by the vm.Script within the context of the current global object. Running code does not have access to local scope, but does have access to the current global object.

下面的示例编译了增加 global 变量的代码，然后多次执行该代码：

¥The following example compiles code that increments a global variable then executes that code multiple times:

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

global.globalVar = 0;

const script = new vm.Script('globalVar += 1', { filename: 'myfile.vm' });

for (let i = 0; i < 1000; ++i) {
  script.runInThisContext();
}

console.log(globalVar);

// 1000 拷贝

类：vm.Module#

¥Class: vm.Module

此特性仅在启用 --experimental-vm-modules 命令标志时可用。

¥This feature is only available with the --experimental-vm-modules command flag enabled.

vm.Module 类为在 VM 上下文中使用 ECMAScript 模块提供了低层接口。它是 vm.Script 类的对应物，密切反映了 ECMAScript 规范中定义的 模块记录。

¥The vm.Module class provides a low-level interface for using ECMAScript modules in VM contexts. It is the counterpart of the vm.Script class that closely mirrors Module Records as defined in the ECMAScript specification.

但是，与 vm.Script 不同，每个 vm.Module 对象都从它的创建开始绑定到上下文。与 vm.Script 对象的同步性质相比，对 vm.Module 对象的操作本质上是异步的。使用 'async' 函数可以帮助操作 vm.Module 对象。

¥Unlike vm.Script however, every vm.Module object is bound to a context from its creation. Operations on vm.Module objects are intrinsically asynchronous, in contrast with the synchronous nature of vm.Script objects. The use of 'async' functions can help with manipulating vm.Module objects.

使用 vm.Module 对象需要三个不同的步骤：创建/解析、链接和评估。以下示例说明了这三个步骤

¥Using a vm.Module object requires three distinct steps: creation/parsing, linking, and evaluation. These three steps are illustrated in the following example.

此实现位于比 ECMAScript 模块加载器 更低的级别。虽然计划提供支持，但也无法与加载器交互。

¥This implementation lies at a lower level than the ECMAScript Module loader. There is also no way to interact with the Loader yet, though support is planned.

import vm from 'node:vm';

const contextifiedObject = vm.createContext({
  secret: 42,
  print: console.log,
});

// Step 1
//
// Create a Module by constructing a new `vm.SourceTextModule` object. This
// parses the provided source text, throwing a `SyntaxError` if anything goes
// wrong. By default, a Module is created in the top context. But here, we
// specify `contextifiedObject` as the context this Module belongs to.
//
// Here, we attempt to obtain the default export from the module "foo", and
// put it into local binding "secret".

const bar = new vm.SourceTextModule(`
  import s from 'foo';
  s;
  print(s);
`, { context: contextifiedObject });

// Step 2
//
// "Link" the imported dependencies of this Module to it.
//
// The provided linking callback (the "linker") accepts two arguments: the
// parent module (`bar` in this case) and the string that is the specifier of
// the imported module. The callback is expected to return a Module that
// corresponds to the provided specifier, with certain requirements documented
// in `module.link()`.
//
// If linking has not started for the returned Module, the same linker
// callback will be called on the returned Module.
//
// Even top-level Modules without dependencies must be explicitly linked. The
// callback provided would never be called, however.
//
// The link() method returns a Promise that will be resolved when all the
// Promises returned by the linker resolve.
//
// Note: This is a contrived example in that the linker function creates a new
// "foo" module every time it is called. In a full-fledged module system, a
// cache would probably be used to avoid duplicated modules.

async function linker(specifier, referencingModule) {
  if (specifier === 'foo') {
    return new vm.SourceTextModule(`
      // The "secret" variable refers to the global variable we added to
      // "contextifiedObject" when creating the context.
      export default secret;
    `, { context: referencingModule.context });

    // Using `contextifiedObject` instead of `referencingModule.context`
    // here would work as well.
  }
  throw new Error(`Unable to resolve dependency: ${specifier}`);
}
await bar.link(linker);

// Step 3
//
// Evaluate the Module. The evaluate() method returns a promise which will
// resolve after the module has finished evaluating.

// Prints 42.
await bar.evaluate();const vm = require('node:vm');

const contextifiedObject = vm.createContext({
  secret: 42,
  print: console.log,
});

(async () => {
  // Step 1
  //
  // Create a Module by constructing a new `vm.SourceTextModule` object. This
  // parses the provided source text, throwing a `SyntaxError` if anything goes
  // wrong. By default, a Module is created in the top context. But here, we
  // specify `contextifiedObject` as the context this Module belongs to.
  //
  // Here, we attempt to obtain the default export from the module "foo", and
  // put it into local binding "secret".

  const bar = new vm.SourceTextModule(`
    import s from 'foo';
    s;
    print(s);
  `, { context: contextifiedObject });

  // Step 2
  //
  // "Link" the imported dependencies of this Module to it.
  //
  // The provided linking callback (the "linker") accepts two arguments: the
  // parent module (`bar` in this case) and the string that is the specifier of
  // the imported module. The callback is expected to return a Module that
  // corresponds to the provided specifier, with certain requirements documented
  // in `module.link()`.
  //
  // If linking has not started for the returned Module, the same linker
  // callback will be called on the returned Module.
  //
  // Even top-level Modules without dependencies must be explicitly linked. The
  // callback provided would never be called, however.
  //
  // The link() method returns a Promise that will be resolved when all the
  // Promises returned by the linker resolve.
  //
  // Note: This is a contrived example in that the linker function creates a new
  // "foo" module every time it is called. In a full-fledged module system, a
  // cache would probably be used to avoid duplicated modules.

  async function linker(specifier, referencingModule) {
    if (specifier === 'foo') {
      return new vm.SourceTextModule(`
        // The "secret" variable refers to the global variable we added to
        // "contextifiedObject" when creating the context.
        export default secret;
      `, { context: referencingModule.context });

      // Using `contextifiedObject` instead of `referencingModule.context`
      // here would work as well.
    }
    throw new Error(`Unable to resolve dependency: ${specifier}`);
  }
  await bar.link(linker);

  // Step 3
  //
  // Evaluate the Module. The evaluate() method returns a promise which will
  // resolve after the module has finished evaluating.

  // Prints 42.
  await bar.evaluate();
})();拷贝

module.dependencySpecifiers#

• <string[]>

该模块所有依赖的说明符。返回的数组被冻结，不允许对其进行任何更改。

¥The specifiers of all dependencies of this module. The returned array is frozen to disallow any changes to it.

对应 ECMAScript 规范中 循环模块记录 的 [[RequestedModules]] 字段。

¥Corresponds to the [[RequestedModules]] field of Cyclic Module Records in the ECMAScript specification.

module.error#

• <any>

如果 module.status 为 'errored'，则该属性包含模块在求值过程中抛出的异常。如果状态是别的，访问这个属性会导致抛出异常。

¥If the module.status is 'errored', this property contains the exception thrown by the module during evaluation. If the status is anything else, accessing this property will result in a thrown exception.

值 undefined 不能用于由于可能与 throw undefined; 有歧义而没有抛出异常的情况。

¥The value undefined cannot be used for cases where there is not a thrown exception due to possible ambiguity with throw undefined;.

对应 ECMAScript 规范中 循环模块记录 的 [[EvaluationError]] 字段。

¥Corresponds to the [[EvaluationError]] field of Cyclic Module Records in the ECMAScript specification.

module.evaluate([options])#

• options <Object>

  • timeout <integer> 指定终止执行前要评估的毫秒数。如果执行中断，则会抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to evaluate before terminating execution. If execution is interrupted, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

评估模块。

¥Evaluate the module.

这必须在模块链接后调用；否则它会拒绝。当模块已经被评估时，它也可以被调用，在这种情况下，如果初始评估成功结束（module.status 是 'evaluated'），则它将不做任何事情，或者它会重新抛出初始评估导致的异常（module.status 是 'errored')。

¥This must be called after the module has been linked; otherwise it will reject. It could be called also when the module has already been evaluated, in which case it will either do nothing if the initial evaluation ended in success (module.status is 'evaluated') or it will re-throw the exception that the initial evaluation resulted in (module.status is 'errored').

在评估模块时无法调用此方法（module.status 为 'evaluating'）。

¥This method cannot be called while the module is being evaluated (module.status is 'evaluating').

对应 ECMAScript 规范中 循环模块记录 的 Evaluate() 具体方法 字段。

¥Corresponds to the Evaluate() concrete method field of Cyclic Module Records in the ECMAScript specification.

module.identifier#

• <string>

当前模块的标识符，在构造函数中设置。

¥The identifier of the current module, as set in the constructor.

module.link(linker)#

• linker <Function>

  • specifier <string> 请求模块的说明符：

    ¥specifier <string> The specifier of the requested module:

    import foo from 'foo';
    //              ^^^^^ the module specifier 拷贝

  • referencingModule <vm.Module> Module 对象 link() 被调用。

    ¥referencingModule <vm.Module> The Module object link() is called on.

  • extra <Object>

    • assert <Object> 来自断言的数据：

      ¥assert <Object> The data from the assertion:

      import foo from 'foo' assert { name: 'value' };
      //                           ^^^^^^^^^^^^^^^^^ the assertion 拷贝

      根据 ECMA-262，主机应该忽略它们不支持的断言，而不是例如在存在不受支持的断言时触发错误。

      ¥Per ECMA-262, hosts are expected to ignore assertions that they do not support, as opposed to, for example, triggering an error if an unsupported assertion is present.

  • 返回：<vm.Module> | <Promise>

    ¥Returns: <vm.Module> | <Promise>

• 返回：<Promise>

  ¥Returns: <Promise>

链接模块依赖。此方法必须在求值前调用，并且每个模块只能调用一次。

¥Link module dependencies. This method must be called before evaluation, and can only be called once per module.

该函数应返回 Module 对象或最终解析为 Module 对象的 Promise。返回的 Module 必须满足以下两个不变量：

¥The function is expected to return a Module object or a Promise that eventually resolves to a Module object. The returned Module must satisfy the following two invariants:

• 它必须与父 Module 属于相同的上下文。

  ¥It must belong to the same context as the parent Module.

• 它的 status 不能是 'errored'。

  ¥Its status must not be 'errored'.

如果返回的 Module 的 status 是 'unlinked'，则将在返回的 Module 上递归调用此方法，并使用相同提供的 linker 函数。

¥If the returned Module's status is 'unlinked', this method will be recursively called on the returned Module with the same provided linker function.

link() 返回 Promise，当所有链接实例都解析为有效的 Module 时，它将被解析，或者如果链接器函数抛出异常或返回无效的 Module，则被拒绝。

¥link() returns a Promise that will either get resolved when all linking instances resolve to a valid Module, or rejected if the linker function either throws an exception or returns an invalid Module.

链接器函数大致对应于 ECMAScript 规范中实现定义的 HostResolveImportedModule 抽象操作，但有几个关键区别：

¥The linker function roughly corresponds to the implementation-defined HostResolveImportedModule abstract operation in the ECMAScript specification, with a few key differences:

• 链接器函数允许异步，而 HostResolveImportedModule 是同步的。

  ¥The linker function is allowed to be asynchronous while HostResolveImportedModule is synchronous.

模块链接期间使用的实际 HostResolveImportedModule 实现是返回链接期间链接的模块的实现。由于此时所有模块都已经完全链接，因此 HostResolveImportedModule 实现根据规范是完全同步的。

¥The actual HostResolveImportedModule implementation used during module linking is one that returns the modules linked during linking. Since at that point all modules would have been fully linked already, the HostResolveImportedModule implementation is fully synchronous per specification.

对应 ECMAScript 规范中 循环模块记录 的 Link() 具体方法 字段。

¥Corresponds to the Link() concrete method field of Cyclic Module Records in the ECMAScript specification.

module.namespace#

• <Object>

模块的命名空间对象。这仅在链接 (module.link()) 完成后可用。

¥The namespace object of the module. This is only available after linking (module.link()) has completed.

对应 ECMAScript 规范中的 GetModuleNamespace 抽象操作。

¥Corresponds to the GetModuleNamespace abstract operation in the ECMAScript specification.

module.status#

• <string>

模块的当前状态。将是以下之一：

¥The current status of the module. Will be one of:

• 'unlinked'：module.link() 还没有被调用。

  ¥'unlinked': module.link() has not yet been called.

• 'linking'：module.link() 已被调用，但链接器函数返回的 Promise 尚未全部解决。

  ¥'linking': module.link() has been called, but not all Promises returned by the linker function have been resolved yet.

• 'linked'：模块已成功链接，其所有依赖都已链接，但尚未调用 module.evaluate()。

  ¥'linked': The module has been linked successfully, and all of its dependencies are linked, but module.evaluate() has not yet been called.

• 'evaluating'：该模块正在通过自身或父模块上的 module.evaluate() 进行评估。

  ¥'evaluating': The module is being evaluated through a module.evaluate() on itself or a parent module.

• 'evaluated'：模块已成功评估。

  ¥'evaluated': The module has been successfully evaluated.

• 'errored'：模块已被评估，但抛出异常。

  ¥'errored': The module has been evaluated, but an exception was thrown.

除了 'errored'，此状态字符串对应于规范的 循环模块记录 的 [[Status]] 字段。'errored' 对应于规范中的 'evaluated'，但 [[EvaluationError]] 设置为不是 undefined 的值。

¥Other than 'errored', this status string corresponds to the specification's Cyclic Module Record's [[Status]] field. 'errored' corresponds to 'evaluated' in the specification, but with [[EvaluationError]] set to a value that is not undefined.

类：vm.SourceTextModule#

¥Class: vm.SourceTextModule

此特性仅在启用 --experimental-vm-modules 命令标志时可用。

¥This feature is only available with the --experimental-vm-modules command flag enabled.

• 继承：<vm.Module>

  ¥Extends: <vm.Module>

vm.SourceTextModule 类提供 ECMAScript 规范中定义的 源文本模块记录。

¥The vm.SourceTextModule class provides the Source Text Module Record as defined in the ECMAScript specification.

new vm.SourceTextModule(code[, options])#

• code <string> 要解析的 JavaScript 模块代码

  ¥code <string> JavaScript Module code to parse

• options

  • identifier <string> 用于堆栈跟踪的字符串。默认值：'vm:module(i)'，其中 i 是上下文特定的升序索引。

    ¥identifier <string> String used in stack traces. Default: 'vm:module(i)' where i is a context-specific ascending index.

  • cachedData <Buffer> | <TypedArray> | <DataView> 为所提供的源提供可选的 Buffer 或 TypedArray 或 DataView，其中包含 V8 的代码缓存数据。code 必须与创建此 cachedData 的模块相同。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source. The code must be the same as the module from which this cachedData was created.

  • context <Object> vm.createContext() 方法返回的 contextified 对象，用于编译和评估此 Module 中的对象。

    ¥context <Object> The contextified object as returned by the vm.createContext() method, to compile and evaluate this Module in.

  • lineOffset <integer> 指定在此 Module 产生的堆栈跟踪中显示的行号偏移量。默认值：0。

    ¥lineOffset <integer> Specifies the line number offset that is displayed in stack traces produced by this Module. Default: 0.

  • columnOffset <integer> 指定在此 Module 生成的堆栈跟踪中显示的第一行列号偏移量。默认值：0。

    ¥columnOffset <integer> Specifies the first-line column number offset that is displayed in stack traces produced by this Module. Default: 0.

  • initializeImportMeta <Function> 在评估此 Module 期间调用以初始化 import.meta。

    ¥initializeImportMeta <Function> Called during evaluation of this Module to initialize the import.meta.

    • meta <import.meta>

    • module <vm.SourceTextModule>

  • importModuleDynamically <Function> 在调用 import() 时在评估此模块期间调用。如果未指定此选项，则调用 import() 将使用 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING 拒绝。

    ¥importModuleDynamically <Function> Called during evaluation of this module when import() is called. If this option is not specified, calls to import() will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING.

    • specifier <string> 说明符传递给 import()

      ¥specifier <string> specifier passed to import()

    • module <vm.Module>

    • importAssertions <Object> 传给 optionsExpression 可选参数的 "assert" 值，如果没有提供值，则为空对象。

      ¥importAssertions <Object> The "assert" value passed to the optionsExpression optional parameter, or an empty object if no value was provided.

    • 返回：<Module Namespace Object> | <vm.Module> 建议返回 vm.Module 以利用错误跟踪，并避免包含 then 函数导出的命名空间出现问题。

      ¥Returns: <Module Namespace Object> | <vm.Module> Returning a vm.Module is recommended in order to take advantage of error tracking, and to avoid issues with namespaces that contain then function exports.

创建新的 SourceTextModule 实例。

¥Creates a new SourceTextModule instance.

分配给作为对象的 import.meta 对象的属性可能允许模块访问指定 context 之外的信息。使用 vm.runInContext() 在特定上下文中创建对象。

¥Properties assigned to the import.meta object that are objects may allow the module to access information outside the specified context. Use vm.runInContext() to create objects in a specific context.

import vm from 'node:vm';

const contextifiedObject = vm.createContext({ secret: 42 });

const module = new vm.SourceTextModule(
  'Object.getPrototypeOf(import.meta.prop).secret = secret;',
  {
    initializeImportMeta(meta) {
      // Note: this object is created in the top context. As such,
      // Object.getPrototypeOf(import.meta.prop) points to the
      // Object.prototype in the top context rather than that in
      // the contextified object.
      meta.prop = {};
    }
  });
// Since module has no dependencies, the linker function will never be called.
await module.link(() => {});
await module.evaluate();

// Now, Object.prototype.secret will be equal to 42.
//
// To fix this problem, replace
//     meta.prop = {};
// above with
//     meta.prop = vm.runInContext('{}', contextifiedObject);const vm = require('node:vm');
const contextifiedObject = vm.createContext({ secret: 42 });
(async () => {
  const module = new vm.SourceTextModule(
    'Object.getPrototypeOf(import.meta.prop).secret = secret;',
    {
      initializeImportMeta(meta) {
        // Note: this object is created in the top context. As such,
        // Object.getPrototypeOf(import.meta.prop) points to the
        // Object.prototype in the top context rather than that in
        // the contextified object.
        meta.prop = {};
      }
    });
  // Since module has no dependencies, the linker function will never be called.
  await module.link(() => {});
  await module.evaluate();
  // Now, Object.prototype.secret will be equal to 42.
  //
  // To fix this problem, replace
  //     meta.prop = {};
  // above with
  //     meta.prop = vm.runInContext('{}', contextifiedObject);
})();拷贝

sourceTextModule.createCachedData()#

• 返回：<Buffer>

  ¥Returns: <Buffer>

创建可与 SourceTextModule 构造函数的 cachedData 选项一起使用的代码缓存。返回 Buffer。在评估模块之前，可以多次调用此方法。

¥Creates a code cache that can be used with the SourceTextModule constructor's cachedData option. Returns a Buffer. This method may be called any number of times before the module has been evaluated.

SourceTextModule 的代码缓存不包含任何 JavaScript 可观察状态。代码缓存可以安全地与脚本源一起保存，并用于多次构造新的 SourceTextModule 实例。

¥The code cache of the SourceTextModule doesn't contain any JavaScript observable states. The code cache is safe to be saved along side the script source and used to construct new SourceTextModule instances multiple times.

SourceTextModule 源代码中的函数可以标记为延迟编译，并且在构建 SourceTextModule 时不会编译它们。这些函数将在第一次调用时被编译。代码缓存序列化 V8 目前知道的关于 SourceTextModule 的元数据，它可以用来加速未来的编译。

¥Functions in the SourceTextModule source can be marked as lazily compiled and they are not compiled at construction of the SourceTextModule. These functions are going to be compiled when they are invoked the first time. The code cache serializes the metadata that V8 currently knows about the SourceTextModule that it can use to speed up future compilations.

// Create an initial module
const module = new vm.SourceTextModule('const a = 1;');

// Create cached data from this module
const cachedData = module.createCachedData();

// Create a new module using the cached data. The code must be the same.
const module2 = new vm.SourceTextModule('const a = 1;', { cachedData }); 拷贝

类：vm.SyntheticModule#

¥Class: vm.SyntheticModule

此特性仅在启用 --experimental-vm-modules 命令标志时可用。

¥This feature is only available with the --experimental-vm-modules command flag enabled.

• 继承：<vm.Module>

  ¥Extends: <vm.Module>

vm.SyntheticModule 类提供了 WebIDL 规范中定义的 合成模块记录。合成模块的目的是提供通用的接口，用于将非 JavaScript 源暴露给 ECMAScript 模块图。

¥The vm.SyntheticModule class provides the Synthetic Module Record as defined in the WebIDL specification. The purpose of synthetic modules is to provide a generic interface for exposing non-JavaScript sources to ECMAScript module graphs.

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

const source = '{ "a": 1 }';
const module = new vm.SyntheticModule(['default'], function() {
  const obj = JSON.parse(source);
  this.setExport('default', obj);
});

// Use `module` in linking... 拷贝

new vm.SyntheticModule(exportNames, evaluateCallback[, options])#

• exportNames <string[]> 将从模块导出的名称数组。

  ¥exportNames <string[]> Array of names that will be exported from the module.

• evaluateCallback <Function> 在评估模块时调用。

  ¥evaluateCallback <Function> Called when the module is evaluated.

• options

  • identifier <string> 用于堆栈跟踪的字符串。默认值：'vm:module(i)'，其中 i 是上下文特定的升序索引。

    ¥identifier <string> String used in stack traces. Default: 'vm:module(i)' where i is a context-specific ascending index.

  • context <Object> vm.createContext() 方法返回的 contextified 对象，用于编译和评估此 Module 中的对象。

    ¥context <Object> The contextified object as returned by the vm.createContext() method, to compile and evaluate this Module in.

创建新的 SyntheticModule 实例。

¥Creates a new SyntheticModule instance.

分配给此实例导出的对象可能允许模块的导入者访问指定 context 之外的信息。使用 vm.runInContext() 在特定上下文中创建对象。

¥Objects assigned to the exports of this instance may allow importers of the module to access information outside the specified context. Use vm.runInContext() to create objects in a specific context.

syntheticModule.setExport(name, value)#

• name <string> 要设置的导出名称。

  ¥name <string> Name of the export to set.

• value <any> 将导出设置为的值。

  ¥value <any> The value to set the export to.

此方法用于模块链接后设置导出的值。如果在链接模块之前调用，则会抛出 ERR_VM_MODULE_STATUS 错误。

¥This method is used after the module is linked to set the values of exports. If it is called before the module is linked, an ERR_VM_MODULE_STATUS error will be thrown.

import vm from 'node:vm';

const m = new vm.SyntheticModule(['x'], () => {
  m.setExport('x', 1);
});

await m.link(() => {});
await m.evaluate();

assert.strictEqual(m.namespace.x, 1);const vm = require('node:vm');
(async () => {
  const m = new vm.SyntheticModule(['x'], () => {
    m.setExport('x', 1);
  });
  await m.link(() => {});
  await m.evaluate();
  assert.strictEqual(m.namespace.x, 1);
})();拷贝

vm.compileFunction(code[, params[, options]])#

• code <string> 要编译的函数体。

  ¥code <string> The body of the function to compile.

• params <string[]> 包含函数所有参数的字符串数组。

  ¥params <string[]> An array of strings containing all parameters for the function.

• options <Object>

  • filename <string> 指定此脚本生成的堆栈跟踪中使用的文件名。默认值：''。

    ¥filename <string> Specifies the filename used in stack traces produced by this script. Default: ''.

  • lineOffset <number> 指定在此脚本生成的堆栈跟踪中显示的行号偏移量。默认值：0。

    ¥lineOffset <number> Specifies the line number offset that is displayed in stack traces produced by this script. Default: 0.

  • columnOffset <number> 指定在此脚本生成的堆栈跟踪中显示的第一行列号偏移量。默认值：0。

    ¥columnOffset <number> Specifies the first-line column number offset that is displayed in stack traces produced by this script. Default: 0.

  • cachedData <Buffer> | <TypedArray> | <DataView> 为所提供的源提供可选的 Buffer 或 TypedArray 或 DataView，其中包含 V8 的代码缓存数据。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source.

  • produceCachedData <boolean> 指定是否产生新的缓存数据。默认值：false。

    ¥produceCachedData <boolean> Specifies whether to produce new cache data. Default: false.

  • parsingContext <Object> 应在其中编译所述函数的 contextified 对象。

    ¥parsingContext <Object> The contextified object in which the said function should be compiled in.

  • contextExtensions <Object[]> 包含要在编译时应用的上下文扩展集合（包含当前作用域的对象）的数组。默认值：[]。

    ¥contextExtensions <Object[]> An array containing a collection of context extensions (objects wrapping the current scope) to be applied while compiling. Default: [].

  • importModuleDynamically <Function> 在调用 import() 时在评估此模块期间调用。如果未指定此选项，则调用 import() 将使用 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING 拒绝。此选项是实验模块 API 的一部分，不应被视为稳定的。

    ¥importModuleDynamically <Function> Called during evaluation of this module when import() is called. If this option is not specified, calls to import() will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. This option is part of the experimental modules API, and should not be considered stable.

    • specifier <string> 说明符传递给 import()

      ¥specifier <string> specifier passed to import()

    • function <Function>

    • importAssertions <Object> 传给 optionsExpression 可选参数的 "assert" 值，如果没有提供值，则为空对象。

      ¥importAssertions <Object> The "assert" value passed to the optionsExpression optional parameter, or an empty object if no value was provided.

    • 返回：<Module Namespace Object> | <vm.Module> 建议返回 vm.Module 以利用错误跟踪，并避免包含 then 函数导出的命名空间出现问题。

      ¥Returns: <Module Namespace Object> | <vm.Module> Returning a vm.Module is recommended in order to take advantage of error tracking, and to avoid issues with namespaces that contain then function exports.

• 返回：<Function>

  ¥Returns: <Function>

将给定的代码编译到提供的上下文中（如果没有提供上下文，则使用当前上下文），并返回它封装在具有给定 params 的函数中。

¥Compiles the given code into the provided context (if no context is supplied, the current context is used), and returns it wrapped inside a function with the given params.

vm.createContext([contextObject[, options]])#

• contextObject <Object>

• options <Object>

  • name <string> 新创建的上下文的可读名称。默认值：'VM Context i'，其中 i 是所创建上下文的升序数字索引。

    ¥name <string> Human-readable name of the newly created context. Default: 'VM Context i', where i is an ascending numerical index of the created context.

  • origin <string> 起源 对应于新创建的上下文，用于显示目的。来源的格式应该像 URL，但只有协议、主机和端口（如果需要），就像 URL 对象的 url.origin 属性的值。最值得注意的是，该字符串应省略尾部斜杠，因为它表示路径。默认值：''。

    ¥origin <string> Origin corresponding to the newly created context for display purposes. The origin should be formatted like a URL, but with only the scheme, host, and port (if necessary), like the value of the url.origin property of a URL object. Most notably, this string should omit the trailing slash, as that denotes a path. Default: ''.

  • codeGeneration <Object>

    • strings <boolean> 如果设置为 false，则任何对 eval 或函数构造函数（Function、GeneratorFunction 等）的调用都将抛出 EvalError。默认值：true。

      ¥strings <boolean> If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) will throw an EvalError. Default: true.

    • wasm <boolean> 如果设置为 false，则任何编译 WebAssembly 模块的尝试都将抛出 WebAssembly.CompileError。默认值：true。

      ¥wasm <boolean> If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. Default: true.

  • microtaskMode <string> 如果设置为 afterEvaluate，微任务（通过 Promise 和 async function 安排的任务）将在脚本运行通过 script.runInContext() 后立即运行。在这种情况下，它们包含在 timeout 和 breakOnSigint 范围内。

    ¥microtaskMode <string> If set to afterEvaluate, microtasks (tasks scheduled through Promises and async functions) will be run immediately after a script has run through script.runInContext(). They are included in the timeout and breakOnSigint scopes in that case.

• 返回：<Object> 上下文对象。

  ¥Returns: <Object> contextified object.

如果给定 contextObject，vm.createContext() 方法将 准备那个对象，以便它可以用于调用 vm.runInContext() 或 script.runInContext()。在此类脚本中，contextObject 将是全局对象，保留其所有现有属性，但也具有任何标准 全局对象 所具有的内置对象和功能。在 vm 模块运行的脚本之外，全局变量将保持不变。

¥If given a contextObject, the vm.createContext() method will prepare that object so that it can be used in calls to vm.runInContext() or script.runInContext(). Inside such scripts, the contextObject will be the global object, retaining all of its existing properties but also having the built-in objects and functions any standard global object has. Outside of scripts run by the vm module, global variables will remain unchanged.

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

global.globalVar = 3;

const context = { globalVar: 1 };
vm.createContext(context);

vm.runInContext('globalVar *= 2;', context);

console.log(context);
// Prints: { globalVar: 2 }

console.log(global.globalVar);
// Prints: 3 拷贝

如果省略 contextObject（或显式传递为 undefined），将返回一个新的空 contextified 对象。

¥If contextObject is omitted (or passed explicitly as undefined), a new, empty contextified object will be returned.

vm.createContext() 方法主要用于创建可用于运行多个脚本的单个上下文。例如，如果模拟网络浏览器，则该方法可用于创建表示窗口全局对象的单个上下文，然后在该上下文中一起运行所有 <script> 标签。

¥The vm.createContext() method is primarily useful for creating a single context that can be used to run multiple scripts. For instance, if emulating a web browser, the method can be used to create a single context representing a window's global object, then run all <script> tags together within that context.

提供的上下文的 name 和 origin 通过检查器 API 可见。

¥The provided name and origin of the context are made visible through the Inspector API.

vm.isContext(object)#

• object <Object>

• 返回：<boolean>

  ¥Returns: <boolean>

如果给定的 object 对象已经是 contextified 使用 vm.createContext()，则返回 true。

¥Returns true if the given object object has been contextified using vm.createContext().

vm.measureMemory([options])#

测量 V8 已知的内存并被当前 V8 隔离已知的所有上下文或主上下文使用。

¥Measure the memory known to V8 and used by all contexts known to the current V8 isolate, or the main context.

• options <Object> 可选的。

  ¥options <Object> Optional.

  • mode <string> 'summary' 或 'detailed'。在摘要模式下，只会返回为主上下文测量的内存。在详细模式下，将返回为当前 V8 隔离已知的所有上下文测量的内存。默认值：'summary'

    ¥mode <string> Either 'summary' or 'detailed'. In summary mode, only the memory measured for the main context will be returned. In detailed mode, the memory measured for all contexts known to the current V8 isolate will be returned. Default: 'summary'

  • execution <string> 'default' 或 'eager'。在默认执行情况下，promise 将在下一次计划的垃圾收集开始后才会解决，这可能需要一段时间（如果程序在下一次 GC 之前退出，则永远不会）。在快速执行情况下，GC 将立即启动以测量内存。默认值：'default'

    ¥execution <string> Either 'default' or 'eager'. With default execution, the promise will not resolve until after the next scheduled garbage collection starts, which may take a while (or never if the program exits before the next GC). With eager execution, the GC will be started right away to measure the memory. Default: 'default'

• 返回：<Promise> 如果成功测量内存，则 promise 将使用包含内存使用信息的对象进行解决。

  ¥Returns: <Promise> If the memory is successfully measured the promise will resolve with an object containing information about the memory usage.

返回的 Promise 可以解决的对象的格式特定于 V8 引擎，并且可能会从 V8 的一个版本更改为下一个版本。

¥The format of the object that the returned Promise may resolve with is specific to the V8 engine and may change from one version of V8 to the next.

返回的结果与 v8.getHeapSpaceStatistics() 返回的统计数据不同，vm.measureMemory() 测量的是 V8 引擎当前实例中每个 V8 特定上下文可访问的内存，而 v8.getHeapSpaceStatistics() 的结果测量的是当前 V8 中每个堆空间占用的内存实例。

¥The returned result is different from the statistics returned by v8.getHeapSpaceStatistics() in that vm.measureMemory() measure the memory reachable by each V8 specific contexts in the current instance of the V8 engine, while the result of v8.getHeapSpaceStatistics() measure the memory occupied by each heap space in the current V8 instance.

const vm = require('node:vm');
// Measure the memory used by the main context.
vm.measureMemory({ mode: 'summary' })
  // This is the same as vm.measureMemory()
  .then((result) => {
    // The current format is:
    // {
    //   total: {
    //      jsMemoryEstimate: 2418479, jsMemoryRange: [ 2418479, 2745799 ]
    //    }
    // }
    console.log(result);
  });

const context = vm.createContext({ a: 1 });
vm.measureMemory({ mode: 'detailed', execution: 'eager' })
  .then((result) => {
    // Reference the context here so that it won't be GC'ed
    // until the measurement is complete.
    console.log(context.a);
    // {
    //   total: {
    //     jsMemoryEstimate: 2574732,
    //     jsMemoryRange: [ 2574732, 2904372 ]
    //   },
    //   current: {
    //     jsMemoryEstimate: 2438996,
    //     jsMemoryRange: [ 2438996, 2768636 ]
    //   },
    //   other: [
    //     {
    //       jsMemoryEstimate: 135736,
    //       jsMemoryRange: [ 135736, 465376 ]
    //     }
    //   ]
    // }
    console.log(result);
  }); 拷贝

vm.runInContext(code, contextifiedObject[, options])#

• code <string> 要编译和运行的 JavaScript 代码。

  ¥code <string> The JavaScript code to compile and run.

• contextifiedObject <Object> code 编译运行时将用作 global 的 contextified 对象。

  ¥contextifiedObject <Object> The contextified object that will be used as the global when the code is compiled and run.

• options <Object> | <string>

  • filename <string> 指定此脚本生成的堆栈跟踪中使用的文件名。默认值：'evalmachine.<anonymous>'。

    ¥filename <string> Specifies the filename used in stack traces produced by this script. Default: 'evalmachine.<anonymous>'.

  • lineOffset <number> 指定在此脚本生成的堆栈跟踪中显示的行号偏移量。默认值：0。

    ¥lineOffset <number> Specifies the line number offset that is displayed in stack traces produced by this script. Default: 0.

  • columnOffset <number> 指定在此脚本生成的堆栈跟踪中显示的第一行列号偏移量。默认值：0。

    ¥columnOffset <number> Specifies the first-line column number offset that is displayed in stack traces produced by this script. Default: 0.

  • displayErrors <boolean> 当为 true 时，如果编译 code 时出现 Error，则导致错误的代码行会附加到堆栈跟踪中。默认值：true。

    ¥displayErrors <boolean> When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.

  • timeout <integer> 指定终止执行前执行 code 的毫秒数。如果执行终止，则将抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

  • cachedData <Buffer> | <TypedArray> | <DataView> 为所提供的源提供可选的 Buffer 或 TypedArray 或 DataView，其中包含 V8 的代码缓存数据。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source.

  • importModuleDynamically <Function> 在调用 import() 时在评估此模块期间调用。如果未指定此选项，则调用 import() 将使用 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING 拒绝。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。

    ¥importModuleDynamically <Function> Called during evaluation of this module when import() is called. If this option is not specified, calls to import() will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. This option is part of the experimental modules API. We do not recommend using it in a production environment.

    • specifier <string> 说明符传递给 import()

      ¥specifier <string> specifier passed to import()

    • script <vm.Script>

    • importAssertions <Object> 传给 optionsExpression 可选参数的 "assert" 值，如果没有提供值，则为空对象。

      ¥importAssertions <Object> The "assert" value passed to the optionsExpression optional parameter, or an empty object if no value was provided.

    • 返回：<Module Namespace Object> | <vm.Module> 建议返回 vm.Module 以利用错误跟踪，并避免包含 then 函数导出的命名空间出现问题。

      ¥Returns: <Module Namespace Object> | <vm.Module> Returning a vm.Module is recommended in order to take advantage of error tracking, and to avoid issues with namespaces that contain then function exports.

• 返回：<any> 脚本中最后一条语句执行的结果。

  ¥Returns: <any> the result of the very last statement executed in the script.

vm.runInContext() 方法编译 code，在 contextifiedObject 的上下文中运行它，然后返回结果。运行代码无权访问本地作用域。contextifiedObject 对象之前必须是使用 vm.createContext() 方法的 contextified。

¥The vm.runInContext() method compiles code, runs it within the context of the contextifiedObject, then returns the result. Running code does not have access to the local scope. The contextifiedObject object must have been previously contextified using the vm.createContext() method.

如果 options 是字符串，则指定文件名。

¥If options is a string, then it specifies the filename.

以下示例使用单个 contextified 对象编译和执行不同的脚本：

¥The following example compiles and executes different scripts using a single contextified object:

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

const contextObject = { globalVar: 1 };
vm.createContext(contextObject);

for (let i = 0; i < 10; ++i) {
  vm.runInContext('globalVar *= 2;', contextObject);
}
console.log(contextObject);
// Prints: { globalVar: 1024 } 拷贝

vm.runInNewContext(code[, contextObject[, options]])#

• code <string> 要编译和运行的 JavaScript 代码。

  ¥code <string> The JavaScript code to compile and run.

• contextObject <Object> 将成为 contextified 的对象。如果为 undefined，则将创建新的对象。

  ¥contextObject <Object> An object that will be contextified. If undefined, a new object will be created.

• options <Object> | <string>

  • filename <string> 指定此脚本生成的堆栈跟踪中使用的文件名。默认值：'evalmachine.<anonymous>'。

    ¥filename <string> Specifies the filename used in stack traces produced by this script. Default: 'evalmachine.<anonymous>'.

  • lineOffset <number> 指定在此脚本生成的堆栈跟踪中显示的行号偏移量。默认值：0。

    ¥lineOffset <number> Specifies the line number offset that is displayed in stack traces produced by this script. Default: 0.

  • columnOffset <number> 指定在此脚本生成的堆栈跟踪中显示的第一行列号偏移量。默认值：0。

    ¥columnOffset <number> Specifies the first-line column number offset that is displayed in stack traces produced by this script. Default: 0.

  • displayErrors <boolean> 当为 true 时，如果编译 code 时出现 Error，则导致错误的代码行会附加到堆栈跟踪中。默认值：true。

    ¥displayErrors <boolean> When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.

  • timeout <integer> 指定终止执行前执行 code 的毫秒数。如果执行终止，则将抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

  • contextName <string> 新创建的上下文的可读名称。默认值：'VM Context i'，其中 i 是所创建上下文的升序数字索引。

    ¥contextName <string> Human-readable name of the newly created context. Default: 'VM Context i', where i is an ascending numerical index of the created context.

  • contextOrigin <string> 起源 对应于新创建的上下文，用于显示目的。来源的格式应该像 URL，但只有协议、主机和端口（如果需要），就像 URL 对象的 url.origin 属性的值。最值得注意的是，该字符串应省略尾部斜杠，因为它表示路径。默认值：''。

    ¥contextOrigin <string> Origin corresponding to the newly created context for display purposes. The origin should be formatted like a URL, but with only the scheme, host, and port (if necessary), like the value of the url.origin property of a URL object. Most notably, this string should omit the trailing slash, as that denotes a path. Default: ''.

  • contextCodeGeneration <Object>

    • strings <boolean> 如果设置为 false，则任何对 eval 或函数构造函数（Function、GeneratorFunction 等）的调用都将抛出 EvalError。默认值：true。

      ¥strings <boolean> If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) will throw an EvalError. Default: true.

    • wasm <boolean> 如果设置为 false，则任何编译 WebAssembly 模块的尝试都将抛出 WebAssembly.CompileError。默认值：true。

      ¥wasm <boolean> If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. Default: true.

  • cachedData <Buffer> | <TypedArray> | <DataView> 为所提供的源提供可选的 Buffer 或 TypedArray 或 DataView，其中包含 V8 的代码缓存数据。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source.

  • importModuleDynamically <Function> 在调用 import() 时在评估此模块期间调用。如果未指定此选项，则调用 import() 将使用 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING 拒绝。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。

    ¥importModuleDynamically <Function> Called during evaluation of this module when import() is called. If this option is not specified, calls to import() will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. This option is part of the experimental modules API. We do not recommend using it in a production environment.

    • specifier <string> 说明符传递给 import()

      ¥specifier <string> specifier passed to import()

    • script <vm.Script>

    • importAssertions <Object> 传给 optionsExpression 可选参数的 "assert" 值，如果没有提供值，则为空对象。

      ¥importAssertions <Object> The "assert" value passed to the optionsExpression optional parameter, or an empty object if no value was provided.

    • 返回：<Module Namespace Object> | <vm.Module> 建议返回 vm.Module 以利用错误跟踪，并避免包含 then 函数导出的命名空间出现问题。

      ¥Returns: <Module Namespace Object> | <vm.Module> Returning a vm.Module is recommended in order to take advantage of error tracking, and to avoid issues with namespaces that contain then function exports.

  • microtaskMode <string> 如果设置为 afterEvaluate，微任务（通过 Promise 和 async function 安排的任务）将在脚本运行后立即运行。在这种情况下，它们包含在 timeout 和 breakOnSigint 范围内。

    ¥microtaskMode <string> If set to afterEvaluate, microtasks (tasks scheduled through Promises and async functions) will be run immediately after the script has run. They are included in the timeout and breakOnSigint scopes in that case.

• 返回：<any> 脚本中最后一条语句执行的结果。

  ¥Returns: <any> the result of the very last statement executed in the script.

vm.runInNewContext() 首先将给定的 contextObject 上下文化（如果作为 undefined 传入，则创建新的 contextObject），编译 code，在创建的上下文中运行它，然后返回结果。运行代码无权访问本地作用域。

¥The vm.runInNewContext() first contextifies the given contextObject (or creates a new contextObject if passed as undefined), compiles the code, runs it within the created context, then returns the result. Running code does not have access to the local scope.

如果 options 是字符串，则指定文件名。

¥If options is a string, then it specifies the filename.

以下示例编译并执行增加全局变量并设置新变量的代码。这些全局变量包含在 contextObject 中。

¥The following example compiles and executes code that increments a global variable and sets a new one. These globals are contained in the contextObject.

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

const contextObject = {
  animal: 'cat',
  count: 2
};

vm.runInNewContext('count += 1; name = "kitty"', contextObject);
console.log(contextObject);
// Prints: { animal: 'cat', count: 3, name: 'kitty' } 拷贝

vm.runInThisContext(code[, options])#

• code <string> 要编译和运行的 JavaScript 代码。

  ¥code <string> The JavaScript code to compile and run.

• options <Object> | <string>

  • filename <string> 指定此脚本生成的堆栈跟踪中使用的文件名。默认值：'evalmachine.<anonymous>'。

    ¥filename <string> Specifies the filename used in stack traces produced by this script. Default: 'evalmachine.<anonymous>'.

  • lineOffset <number> 指定在此脚本生成的堆栈跟踪中显示的行号偏移量。默认值：0。

    ¥lineOffset <number> Specifies the line number offset that is displayed in stack traces produced by this script. Default: 0.

  • columnOffset <number> 指定在此脚本生成的堆栈跟踪中显示的第一行列号偏移量。默认值：0。

    ¥columnOffset <number> Specifies the first-line column number offset that is displayed in stack traces produced by this script. Default: 0.

  • displayErrors <boolean> 当为 true 时，如果编译 code 时出现 Error，则导致错误的代码行会附加到堆栈跟踪中。默认值：true。

    ¥displayErrors <boolean> When true, if an Error occurs while compiling the code, the line of code causing the error is attached to the stack trace. Default: true.

  • timeout <integer> 指定终止执行前执行 code 的毫秒数。如果执行终止，则将抛出 Error。此值必须是严格的正整数。

    ¥timeout <integer> Specifies the number of milliseconds to execute code before terminating execution. If execution is terminated, an Error will be thrown. This value must be a strictly positive integer.

  • breakOnSigint <boolean> 如果是 true，接收 SIGINT（Ctrl+C）将终止执行并抛出 Error。已通过 process.on('SIGINT') 附加的事件的现有句柄在脚本执行期间被禁用，但在此之后继续工作。默认值：false。

    ¥breakOnSigint <boolean> If true, receiving SIGINT (Ctrl+C) will terminate execution and throw an Error. Existing handlers for the event that have been attached via process.on('SIGINT') are disabled during script execution, but continue to work after that. Default: false.

  • cachedData <Buffer> | <TypedArray> | <DataView> 为所提供的源提供可选的 Buffer 或 TypedArray 或 DataView，其中包含 V8 的代码缓存数据。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source.

  • importModuleDynamically <Function> 在调用 import() 时在评估此模块期间调用。如果未指定此选项，则调用 import() 将使用 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING 拒绝。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。

    ¥importModuleDynamically <Function> Called during evaluation of this module when import() is called. If this option is not specified, calls to import() will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. This option is part of the experimental modules API. We do not recommend using it in a production environment.

    • specifier <string> 说明符传递给 import()

      ¥specifier <string> specifier passed to import()

    • script <vm.Script>

    • importAssertions <Object> 传给 optionsExpression 可选参数的 "assert" 值，如果没有提供值，则为空对象。

      ¥importAssertions <Object> The "assert" value passed to the optionsExpression optional parameter, or an empty object if no value was provided.

    • 返回：<Module Namespace Object> | <vm.Module> 建议返回 vm.Module 以利用错误跟踪，并避免包含 then 函数导出的命名空间出现问题。

      ¥Returns: <Module Namespace Object> | <vm.Module> Returning a vm.Module is recommended in order to take advantage of error tracking, and to avoid issues with namespaces that contain then function exports.

• 返回：<any> 脚本中最后一条语句执行的结果。

  ¥Returns: <any> the result of the very last statement executed in the script.

vm.runInThisContext() 编译 code，在当前 global 的上下文中运行它并返回结果。运行代码无权访问局部作用域，但可以访问当前 global 对象。

¥vm.runInThisContext() compiles code, runs it within the context of the current global and returns the result. Running code does not have access to local scope, but does have access to the current global object.

如果 options 是字符串，则指定文件名。

¥If options is a string, then it specifies the filename.

以下示例说明使用 vm.runInThisContext() 和 JavaScript eval() 函数来运行相同的代码：

¥The following example illustrates using both vm.runInThisContext() and the JavaScript eval() function to run the same code:

const vm = require('node:vm');
let localVar = 'initial value';

const vmResult = vm.runInThisContext('localVar = "vm";');
console.log(`vmResult: '${vmResult}', localVar: '${localVar}'`);
// Prints: vmResult: 'vm', localVar: 'initial value'

const evalResult = eval('localVar = "eval";');
console.log(`evalResult: '${evalResult}', localVar: '${localVar}'`);
// Prints: evalResult: 'eval', localVar: 'eval' 拷贝

因为 vm.runInThisContext() 无权访问本地作用域，所以 localVar 不变。相比之下，eval() 确实可以访问本地范围，因此更改了 localVar 的值。这样 vm.runInThisContext() 很像 间接 eval() 调用，例如 (0,eval)('code')。

¥Because vm.runInThisContext() does not have access to the local scope, localVar is unchanged. In contrast, eval() does have access to the local scope, so the value localVar is changed. In this way vm.runInThisContext() is much like an indirect eval() call, e.g. (0,eval)('code').

示例：在虚拟机中运行 HTTP 服务器#

¥Example: Running an HTTP server within a VM

当使用 script.runInThisContext() 或 vm.runInThisContext() 时，代码在当前 V8 全局上下文中执行。传给此 VM 上下文的代码将有自己的隔离作用域。

¥When using either script.runInThisContext() or vm.runInThisContext(), the code is executed within the current V8 global context. The code passed to this VM context will have its own isolated scope.

为了使用 node:http 模块运行简单的 web 服务器，传给上下文的代码必须要么自己调用 require('node:http')，要么有对传给它的 node:http 模块的引用。例如：

¥In order to run a simple web server using the node:http module the code passed to the context must either call require('node:http') on its own, or have a reference to the node:http module passed to it. For instance:

'use strict';
const vm = require('node:vm');

const code = `
((require) => {
  const http = require('node:http');

  http.createServer((request, response) => {
    response.writeHead(200, { 'Content-Type': 'text/plain' });
    response.end('Hello World\\n');
  }).listen(8124);

  console.log('Server running at http://127.0.0.1:8124/');
})`;

vm.runInThisContext(code)(require); 拷贝

上述案例中的 require() 与其传入的上下文共享状态。当执行不受信任的代码时，这可能会带来风险，例如以不需要的方式更改上下文中的对象。

¥The require() in the above case shares the state with the context it is passed from. This may introduce risks when untrusted code is executed, e.g. altering objects in the context in unwanted ways.

"contextify" 一个对象是什么意思？#

¥What does it mean to "contextify" an object?

在 Node.js 中执行的所有 JavaScript 都在 "context" 的范围内运行。根据 V8 嵌入器指南：

¥All JavaScript executed within Node.js runs within the scope of a "context". According to the V8 Embedder's Guide:

在 V8 中，上下文是一个执行环境，它允许独立的、不相关的 JavaScript 应用在 V8 的单个实例中运行。你必须明确指定要运行任何 JavaScript 代码的上下文。

¥In V8, a context is an execution environment that allows separate, unrelated, JavaScript applications to run in a single instance of V8. You must explicitly specify the context in which you want any JavaScript code to be run.

当方法 vm.createContext() 被调用时，contextObject 参数（或者新创建的对象，如果 contextObject 是 undefined）在内部与 V8 上下文的新实例相关联。这个 V8 上下文使用 node:vm 模块的方法提供了 code 运行，它可以在隔离的全局环境中运行。创建 V8 Context 并将其与 contextObject 相关联的过程就是本文档所指的 "contextifying" 对象。

¥When the method vm.createContext() is called, the contextObject argument (or a newly-created object if contextObject is undefined) is associated internally with a new instance of a V8 Context. This V8 Context provides the code run using the node:vm module's methods with an isolated global environment within which it can operate. The process of creating the V8 Context and associating it with the contextObject is what this document refers to as "contextifying" the object.

与异步任务和 Promises 的超时交互#

¥Timeout interactions with asynchronous tasks and Promises

Promise 和 async function 可以异步调度 JavaScript 引擎运行的任务。默认情况下，这些任务在当前堆栈上的所有 JavaScript 函数执行完毕后运行。这允许转义 timeout 和 breakOnSigint 选项的功能。

¥Promises and async functions can schedule tasks run by the JavaScript engine asynchronously. By default, these tasks are run after all JavaScript functions on the current stack are done executing. This allows escaping the functionality of the timeout and breakOnSigint options.

例如，以下代码由 vm.runInNewContext() 执行，超时时间为 5 毫秒，它安排了一个无限循环在 promise 解决后运行。计划的循环永远不会被超时中断：

¥For example, the following code executed by vm.runInNewContext() with a timeout of 5 milliseconds schedules an infinite loop to run after a promise resolves. The scheduled loop is never interrupted by the timeout:

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

function loop() {
  console.log('entering loop');
  while (1) console.log(Date.now());
}

vm.runInNewContext(
  'Promise.resolve().then(() => loop());',
  { loop, console },
  { timeout: 5 }
);
// This is printed *before* 'entering loop' (!)
console.log('done executing'); 拷贝

这可以通过将 microtaskMode: 'afterEvaluate' 传给创建 Context 的代码来解决：

¥This can be addressed by passing microtaskMode: 'afterEvaluate' to the code that creates the Context:

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

function loop() {
  while (1) console.log(Date.now());
}

vm.runInNewContext(
  'Promise.resolve().then(() => loop());',
  { loop, console },
  { timeout: 5, microtaskMode: 'afterEvaluate' }
); 拷贝

在这种情况下，通过 promise.then() 调度的微任务将在从 vm.runInNewContext() 返回之前运行，并会被 timeout 功能中断。这仅适用于在 vm.Context 中运行的代码，因此例如 vm.runInThisContext() 不采用此选项。

¥In this case, the microtask scheduled through promise.then() will be run before returning from vm.runInNewContext(), and will be interrupted by the timeout functionality. This applies only to code running in a vm.Context, so e.g. vm.runInThisContext() does not take this option.

Promise 回调被输入到创建它们的上下文的微任务队列中。例如，如果在上面的例子中 () => loop() 只被 loop 替换，那么 loop 将被推入全局微任务队列，因为它是来自外部（主）上下文的函数，因此也将能够脱离超时。

¥Promise callbacks are entered into the microtask queue of the context in which they were created. For example, if () => loop() is replaced with just loop in the above example, then loop will be pushed into the global microtask queue, because it is a function from the outer (main) context, and thus will also be able to escape the timeout.

如果 process.nextTick()、queueMicrotask()、setTimeout()、setImmediate() 等异步调度函数在 vm.Context 中可用，传递给它们的函数将被添加到全局队列中，全局队列由所有上下文共享。因此，传给这些函数的回调也无法通过超时控制。

¥If asynchronous scheduling functions such as process.nextTick(), queueMicrotask(), setTimeout(), setImmediate(), etc. are made available inside a vm.Context, functions passed to them will be added to global queues, which are shared by all contexts. Therefore, callbacks passed to those functions are not controllable through the timeout either.