Node.js v20.18.0 文档

类：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> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> 用于指定在调用 import() 时评估此脚本期间应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

    ¥importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Used to specify how the modules should be loaded during the evaluation of this script when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

如果 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> | <undefined> vm.constants.DONT_CONTEXTIFY 或将成为 contextified 的对象。如果是 undefined，将创建一个空的上下文化对象以实现向后兼容。

  ¥contextObject <Object> | <undefined> Either vm.constants.DONT_CONTEXTIFY or an object that will be contextified. If undefined, an empty contextified object will be created for backwards compatibility.

• 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.

此方法是 script.runInContext(vm.createContext(options), options) 的快捷方式。它同时做几件事：

¥This method is a shortcut to script.runInContext(vm.createContext(options), options). It does several things at once:

1. 创建一个新的上下文。

   ¥Creates a new context.

2. 如果 contextObject 是一个对象，则使用新上下文对其进行 contextifies 操作。如果 contextObject 未定义，则创建一个新对象并对其进行 contextifies 操作。如果 contextObject 是 vm.constants.DONT_CONTEXTIFY，则不要 contextify 任何内容。

   ¥If contextObject is an object, contextifies it with the new context. If contextObject is undefined, creates a new object and contextifies it. If contextObject is vm.constants.DONT_CONTEXTIFY, don't contextify anything.

3. 在创建的上下文中运行 vm.Script 对象包含的编译代码。代码无权访问调用此方法的范围。

   ¥Runs the compiled code contained by the vm.Script object within the created context. The code does not have access to the scope in which this method is called.

4. 返回结果。

   ¥Returns the result.

以下示例编译设置全局变量的代码，然后在不同的上下文中多次执行代码。全局变量设置并包含在每个单独的 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' }]

// This would throw if the context is created from a contextified object.
// vm.constants.DONT_CONTEXTIFY allows creating contexts with ordinary
// global objects that can be frozen.
const freezeScript = new vm.Script('Object.freeze(globalThis); globalThis;');
const frozenContext = freezeScript.runInNewContext(vm.constants.DONT_CONTEXTIFY); 拷贝

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 拷贝

script.sourceMapURL#

• <string> | <undefined>

当脚本从包含源映射魔术注释的源编译时，此属性将设置为源映射的 URL。

¥When the script is compiled from a source that contains a source map magic comment, this property will be set to the URL of the source map.

import vm from 'node:vm';

const script = new vm.Script(`
function myFunc() {}
//# sourceMappingURL=sourcemap.json
`);

console.log(script.sourceMapURL);
// Prints: sourcemap.jsonconst vm = require('node:vm');

const script = new vm.Script(`
function myFunc() {}
//# sourceMappingURL=sourcemap.json
`);

console.log(script.sourceMapURL);
// Prints: sourcemap.json拷贝

类：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>

    • attributes <Object> 来自属性的数据：

      ¥attributes <Object> The data from the attribute:

      import foo from 'foo' with { name: 'value' };
      //                         ^^^^^^^^^^^^^^^^^ the attribute 拷贝

      根据 ECMA-262，如果存在不受支持的属性，主机预计会触发错误。

      ¥Per ECMA-262, hosts are expected to trigger an error if an unsupported attribute is present.

    • assert <Object> extra.attributes 的别名。

      ¥assert <Object> Alias for extra.attributes.

  • 返回：<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. If no context is specified, the module is evaluated in the current execution context.

  • 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() 时评估该模块期间应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

    ¥importModuleDynamically <Function> Used to specify the how the modules should be loaded during the evaluation of this module when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

创建新的 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 的代码缓存数据。这必须通过使用相同的 code 和 params 预先调用 vm.compileFunction() 来生成。

    ¥cachedData <Buffer> | <TypedArray> | <DataView> Provides an optional Buffer or TypedArray, or DataView with V8's code cache data for the supplied source. This must be produced by a prior call to vm.compileFunction() with the same code and params.

  • 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> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> 用于指定在调用 import() 时评估此函数期间应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

  ¥importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Used to specify the how the modules should be loaded during the evaluation of this function when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

• 返回：<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.constants#

• <Object>

返回一个包含 VM 操作常用常量的对象。

¥Returns an object containing commonly used constants for VM operations.

vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER#

一个常量，可用作 vm.Script 和 vm.compileFunction() 的 importModuleDynamically 选项，以便 Node.js 使用主上下文中的默认 ESM 加载器来加载请求的模块。

¥A constant that can be used as the importModuleDynamically option to vm.Script and vm.compileFunction() so that Node.js uses the default ESM loader from the main context to load the requested module.

详细信息参见 编译 API 中支持动态 import()。

¥For detailed information, see Support of dynamic import() in compilation APIs.

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

• contextObject <Object> | <undefined> vm.constants.DONT_CONTEXTIFY 或将成为 contextified 的对象。如果是 undefined，将创建一个空的上下文化对象以实现向后兼容。

  ¥contextObject <Object> | <undefined> Either vm.constants.DONT_CONTEXTIFY or an object that will be contextified. If undefined, an empty contextified object will be created for backwards compatibility.

• 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.

  • importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> 用于指定在没有引用脚本或模块的情况下在此上下文中调用 import() 时应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

    ¥importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Used to specify the how the modules should be loaded when import() is called in this context without a referrer script or module. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

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

  ¥Returns: <Object> contextified object.

如果给定的 contextObject 是一个对象，则 vm.createContext() 方法将 准备那个对象 并返回对它的引用，以便可以在对 vm.runInContext() 或 script.runInContext() 的调用中使用它。在这样的脚本中，全局对象将被 contextObject 封装，保留其所有现有属性，但也具有任何标准 全局对象 所具有的内置对象和函数。在 vm 模块运行的脚本之外，全局变量将保持不变。

¥If the given contextObject is an object, the vm.createContext() method will prepare that object and return a reference to it so that it can be used in calls to vm.runInContext() or script.runInContext(). Inside such scripts, the global object will be wrapped by the contextObject, 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.

当新创建的上下文中的全局对象是 contextified 时，与普通全局对象相比，它有一些怪癖。例如，它不能被冻结。要创建没有上下文怪癖的上下文，请将 vm.constants.DONT_CONTEXTIFY 作为 contextObject 参数传递。有关详细信息，请参阅 vm.constants.DONT_CONTEXTIFY 的文档。

¥When the global object in the newly created context is contextified, it has some quirks compared to ordinary global objects. For example, it cannot be frozen. To create a context without the contextifying quirks, pass vm.constants.DONT_CONTEXTIFY as the contextObject argument. See the documentation of vm.constants.DONT_CONTEXTIFY for details.

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 对象已使用 vm.createContext() contextified，或者它是使用 vm.constants.DONT_CONTEXTIFY 创建的上下文的全局对象，则返回 true。

¥Returns true if the given object object has been contextified using vm.createContext(), or if it's the global object of a context created using vm.constants.DONT_CONTEXTIFY.

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 将使用包含有关内存使用信息的对象进行解析。否则它将被拒绝并出现 ERR_CONTEXT_NOT_INITIALIZED 错误。

  ¥Returns: <Promise> If the memory is successfully measured, the promise will resolve with an object containing information about the memory usage. Otherwise it will be rejected with an ERR_CONTEXT_NOT_INITIALIZED error.

返回的 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> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> 用于指定在调用 import() 时评估此脚本期间应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

    ¥importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Used to specify the how the modules should be loaded during the evaluation of this script when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

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> | <undefined> vm.constants.DONT_CONTEXTIFY 或将成为 contextified 的对象。如果是 undefined，将创建一个空的上下文化对象以实现向后兼容。

  ¥contextObject <Object> | <undefined> Either vm.constants.DONT_CONTEXTIFY or an object that will be contextified. If undefined, an empty contextified object will be created for backwards compatibility.

• 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> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> 用于指定在调用 import() 时评估此脚本期间应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

    ¥importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Used to specify the how the modules should be loaded during the evaluation of this script when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

  • 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.

此方法是 (new vm.Script(code, options)).runInContext(vm.createContext(options), options) 的快捷方式。如果 options 是字符串，则指定文件名。

¥This method is a shortcut to (new vm.Script(code, options)).runInContext(vm.createContext(options), options). If options is a string, then it specifies the filename.

它同时做几件事：

¥It does several things at once:

1. 创建一个新的上下文。

   ¥Creates a new context.

2. 如果 contextObject 是一个对象，则使用新上下文对其进行 contextifies 操作。如果 contextObject 未定义，则创建一个新对象并对其进行 contextifies 操作。如果 contextObject 是 vm.constants.DONT_CONTEXTIFY，则不要 contextify 任何内容。

   ¥If contextObject is an object, contextifies it with the new context. If contextObject is undefined, creates a new object and contextifies it. If contextObject is vm.constants.DONT_CONTEXTIFY, don't contextify anything.

3. 将代码编译为 avm.Script

   ¥Compiles the code as avm.Script

4. 在创建的上下文中运行编译代码。代码无权访问调用此方法的范围。

   ¥Runs the compield code within the created context. The code does not have access to the scope in which this method is called.

5. 返回结果。

   ¥Returns the result.

以下示例编译并执行增加全局变量并设置新变量的代码。这些全局变量包含在 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' }

// This would throw if the context is created from a contextified object.
// vm.constants.DONT_CONTEXTIFY allows creating contexts with ordinary global objects that
// can be frozen.
const frozenContext = vm.runInNewContext('Object.freeze(globalThis); globalThis;', vm.constants.DONT_CONTEXTIFY); 拷贝

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> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> 用于指定在调用 import() 时评估此脚本期间应如何加载模块。此选项是实验模块 API 的一部分。不建议在生产环境中使用它。详细信息参见 编译 API 中支持动态 import()。

    ¥importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Used to specify the how the modules should be loaded during the evaluation of this script when import() is called. This option is part of the experimental modules API. We do not recommend using it in a production environment. For detailed information, see Support of dynamic import() in compilation APIs.

• 返回：<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 参数将用于封装 V8 上下文新实例的全局对象（如果 contextObject 是 undefined，则在上下文化之前将从当前上下文创建一个新对象）。这个 V8 上下文使用 node:vm 模块的方法提供了 code 运行，它可以在隔离的全局环境中运行。创建 V8 上下文并将其与外部上下文中的 contextObject 关联的过程就是本文档所称的 "contextifying" 对象。

¥When the method vm.createContext() is called with an object, the contextObject argument will be used to wrap the global object of a new instance of a V8 Context (if contextObject is undefined, a new object will be created from the current context before its contextified). 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 in the outer context is what this document refers to as "contextifying" the object.

上下文化会给上下文中的 globalThis 值带来一些怪癖。例如，它不能被冻结，并且它在外部上下文中不等于 contextObject 的引用。

¥The contextifying would introduce some quirks to the globalThis value in the context. For example, it cannot be frozen, and it is not reference equal to the contextObject in the outer context.

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

// An undefined `contextObject` option makes the global object contextified.
const context = vm.createContext();
console.log(vm.runInContext('globalThis', context) === context);  // false
// A contextified global object cannot be frozen.
try {
  vm.runInContext('Object.freeze(globalThis);', context);
} catch (e) {
  console.log(e); // TypeError: Cannot freeze
}
console.log(vm.runInContext('globalThis.foo = 1; foo;', context));  // 1 拷贝

要使用普通全局对象创建上下文并以较少的怪癖访问外部上下文中的全局代理，请将 vm.constants.DONT_CONTEXTIFY 指定为 contextObject 参数。

¥To create a context with an ordinary global object and get access to a global proxy in the outer context with fewer quirks, specify vm.constants.DONT_CONTEXTIFY as the contextObject argument.

vm.constants.DONT_CONTEXTIFY#

当此常量用作 vm API 中的 contextObject 参数时，它会指示 Node.js 创建上下文，而无需以 Node.js 特定的方式将其全局对象与另一个对象封装在一起。因此，新上下文中的 globalThis 值将更接近普通值。

¥This constant, when used as the contextObject argument in vm APIs, instructs Node.js to create a context without wrapping its global object with another object in a Node.js-specific manner. As a result, the globalThis value inside the new context would behave more closely to an ordinary one.

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

// Use vm.constants.DONT_CONTEXTIFY to freeze the global object.
const context = vm.createContext(vm.constants.DONT_CONTEXTIFY);
vm.runInContext('Object.freeze(globalThis);', context);
try {
  vm.runInContext('bar = 1; bar;', context);
} catch (e) {
  console.log(e); // Uncaught ReferenceError: bar is not defined
} 拷贝

当 vm.constants.DONT_CONTEXTIFY 用作 vm.createContext() 的 contextObject 参数时，返回的对象是新创建的上下文中的全局对象的代理类对象，具有较少的 Node.js 特定怪癖。它在新上下文中引用等于 globalThis 值，可以从上下文外部进行修改，并且可用于直接访问新上下文中的内置函数。

¥When vm.constants.DONT_CONTEXTIFY is used as the contextObject argument to vm.createContext(), the returned object is a proxy-like object to the global object in the newly created context with fewer Node.js-specific quirks. It is reference equal to the globalThis value in the new context, can be modified from outside the context, and can be used to access built-ins in the new context directly.

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

const context = vm.createContext(vm.constants.DONT_CONTEXTIFY);

// Returned object is reference equal to globalThis in the new context.
console.log(vm.runInContext('globalThis', context) === context);  // true

// Can be used to access globals in the new context directly.
console.log(context.Array);  // [Function: Array]
vm.runInContext('foo = 1;', context);
console.log(context.foo);  // 1
context.bar = 1;
console.log(vm.runInContext('bar;', context));  // 1

// Can be frozen and it affects the inner context.
Object.freeze(context);
try {
  vm.runInContext('baz = 1; baz;', context);
} catch (e) {
  console.log(e); // Uncaught ReferenceError: baz is not defined
} 拷贝

与异步任务和 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.

编译 API 中支持动态 import()#

¥Support of dynamic import() in compilation APIs

以下 API 支持 importModuleDynamically 选项，以在 vm 模块编译的代码中启用动态 import()。

¥The following APIs support an importModuleDynamically option to enable dynamic import() in code compiled by the vm module.

• new vm.Script

• vm.compileFunction()

• new vm.SourceTextModule

• vm.runInThisContext()

• vm.runInContext()

• vm.runInNewContext()

• vm.createContext()

此选项仍然是实验模块 API 的一部分。不建议在生产环境中使用它。

¥This option is still part of the experimental modules API. We do not recommend using it in a production environment.

当未指定或未定义 importModuleDynamically 选项时#

¥When the importModuleDynamically option is not specified or undefined

如果未指定此选项，或者如果是 undefined，则包含 import() 的代码仍可以由 vm API 编译，但当执行编译后的代码并实际调用 import() 时，结果将拒绝并显示 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING。

¥If this option is not specified, or if it's undefined, code containing import() can still be compiled by the vm APIs, but when the compiled code is executed and it actually calls import(), the result will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING.

当 importModuleDynamically 为 vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER 时#

¥When importModuleDynamically is vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER

vm.SourceTextModule 目前不支持此选项。

¥This option is currently not supported for vm.SourceTextModule.

使用此选项，当在编译的代码中启动 import() 时，Node.js 将使用主上下文中的默认 ESM 加载器来加载请求的模块并将其返回到正在执行的代码。

¥With this option, when an import() is initiated in the compiled code, Node.js would use the default ESM loader from the main context to load the requested module and return it to the code being executed.

这使得正在编译的代码可以访问 Node.js 内置模块，例如 fs 或 http。如果代码在不同的上下文中执行，请注意从主上下文加载的模块创建的对象仍然来自主上下文，而不是新上下文中的 instanceof 内置类。

¥This gives access to Node.js built-in modules such as fs or http to the code being compiled. If the code is executed in a different context, be aware that the objects created by modules loaded from the main context are still from the main context and not instanceof built-in classes in the new context.

const { Script, constants } = require('node:vm');
const script = new Script(
  'import("node:fs").then(({readFile}) => readFile instanceof Function)',
  { importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER });

// false: URL loaded from the main context is not an instance of the Function
// class in the new context.
script.runInNewContext().then(console.log);import { Script, constants } from 'node:vm';

const script = new Script(
  'import("node:fs").then(({readFile}) => readFile instanceof Function)',
  { importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER });

// false: URL loaded from the main context is not an instance of the Function
// class in the new context.
script.runInNewContext().then(console.log);拷贝

此选项还允许脚本或函数加载用户模块：

¥This option also allows the script or function to load user modules:

import { Script, constants } from 'node:vm';
import { resolve } from 'node:path';
import { writeFileSync } from 'node:fs';

// Write test.js and test.txt to the directory where the current script
// being run is located.
writeFileSync(resolve(import.meta.dirname, 'test.mjs'),
              'export const filename = "./test.json";');
writeFileSync(resolve(import.meta.dirname, 'test.json'),
              '{"hello": "world"}');

// Compile a script that loads test.mjs and then test.json
// as if the script is placed in the same directory.
const script = new Script(
  `(async function() {
    const { filename } = await import('./test.mjs');
    return import(filename, { with: { type: 'json' } })
  })();`,
  {
    filename: resolve(import.meta.dirname, 'test-with-default.js'),
    importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
  });

// { default: { hello: 'world' } }
script.runInThisContext().then(console.log);const { Script, constants } = require('node:vm');
const { resolve } = require('node:path');
const { writeFileSync } = require('node:fs');

// Write test.js and test.txt to the directory where the current script
// being run is located.
writeFileSync(resolve(__dirname, 'test.mjs'),
              'export const filename = "./test.json";');
writeFileSync(resolve(__dirname, 'test.json'),
              '{"hello": "world"}');

// Compile a script that loads test.mjs and then test.json
// as if the script is placed in the same directory.
const script = new Script(
  `(async function() {
    const { filename } = await import('./test.mjs');
    return import(filename, { with: { type: 'json' } })
  })();`,
  {
    filename: resolve(__dirname, 'test-with-default.js'),
    importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
  });

// { default: { hello: 'world' } }
script.runInThisContext().then(console.log);拷贝

使用主上下文中的默认加载器加载用户模块有一些注意事项：

¥There are a few caveats with loading user modules using the default loader from the main context:

1. 正在解析的模块将与传递给 vm.Script 或 vm.compileFunction() 的 filename 选项相关。该解析可以使用绝对路径或 URL 字符串的 filename。如果 filename 是一个既不是绝对路径也不是 URL 的字符串，或者未定义，则解析将相对于进程的当前工作目录。在 vm.createContext() 的情况下，解析始终相对于当前工作目录，因为仅当没有引用脚本或模块时才使用此选项。

   ¥The module being resolved would be relative to the filename option passed to vm.Script or vm.compileFunction(). The resolution can work with a filename that's either an absolute path or a URL string. If filename is a string that's neither an absolute path or a URL, or if it's undefined, the resolution will be relative to the current working directory of the process. In the case of vm.createContext(), the resolution is always relative to the current working directory since this option is only used when there isn't a referrer script or module.

2. 对于解析为特定路径的任何给定 filename，一旦进程设法从该路径加载特定模块，结果可能会被缓存，并且从同一路径加载同一模块的后续加载将返回相同的内容。如果 filename 是一个 URL 字符串，那么如果它具有不同的搜索参数，则不会命中缓存。对于不是 URL 字符串的 filename，目前无法绕过缓存行为。

   ¥For any given filename that resolves to a specific path, once the process manages to load a particular module from that path, the result may be cached, and subsequent load of the same module from the same path would return the same thing. If the filename is a URL string, the cache would not be hit if it has different search parameters. For filenames that are not URL strings, there is currently no way to bypass the caching behavior.

当 importModuleDynamically 是函数时#

¥When importModuleDynamically is a function

当 importModuleDynamically 是一个函数时，当编译代码中调用 import() 时，它将被调用，以便用户自定义所请求的模块应如何编译和评估。目前，必须使用 --experimental-vm-modules 标志启动 Node.js 实例才能使此选项发挥作用。如果未设置该标志，则该回调将被忽略。如果评估的代码实际上调用了 import()，则结果将拒绝并显示 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG。

¥When importModuleDynamically is a function, it will be invoked when import() is called in the compiled code for users to customize how the requested module should be compiled and evaluated. Currently, the Node.js instance must be launched with the --experimental-vm-modules flag for this option to work. If the flag isn't set, this callback will be ignored. If the code evaluated actually calls to import(), the result will reject with ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG.

回调 importModuleDynamically(specifier, referrer, importAttributes) 具有以下签名：

¥The callback importModuleDynamically(specifier, referrer, importAttributes) has the following signature:

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

  ¥specifier <string> specifier passed to import()

• referrer <vm.Script> | <Function> | <vm.SourceTextModule> | <Object> 引用者是针对 new vm.Script、vm.runInThisContext、vm.runInContext 和 vm.runInNewContext 编译的 vm.Script。vm.compileFunction 是编译后的 Function，new vm.SourceTextModule 是编译后的 vm.SourceTextModule，vm.createContext() 是上下文 Object。

  ¥referrer <vm.Script> | <Function> | <vm.SourceTextModule> | <Object> The referrer is the compiled vm.Script for new vm.Script, vm.runInThisContext, vm.runInContext and vm.runInNewContext. It's the compiled Function for vm.compileFunction, the compiled vm.SourceTextModule for new vm.SourceTextModule, and the context Object for vm.createContext().

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

  ¥importAttributes <Object> The "with" 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.

// This script must be run with --experimental-vm-modules.
import { Script, SyntheticModule } from 'node:vm';

const script = new Script('import("foo.json", { with: { type: "json" } })', {
  async importModuleDynamically(specifier, referrer, importAttributes) {
    console.log(specifier);  // 'foo.json'
    console.log(referrer);   // The compiled script
    console.log(importAttributes);  // { type: 'json' }
    const m = new SyntheticModule(['bar'], () => { });
    await m.link(() => { });
    m.setExport('bar', { hello: 'world' });
    return m;
  },
});
const result = await script.runInThisContext();
console.log(result);  //  { bar: { hello: 'world' } }// This script must be run with --experimental-vm-modules.
const { Script, SyntheticModule } = require('node:vm');

(async function main() {
  const script = new Script('import("foo.json", { with: { type: "json" } })', {
    async importModuleDynamically(specifier, referrer, importAttributes) {
      console.log(specifier);  // 'foo.json'
      console.log(referrer);   // The compiled script
      console.log(importAttributes);  // { type: 'json' }
      const m = new SyntheticModule(['bar'], () => { });
      await m.link(() => { });
      m.setExport('bar', { hello: 'world' });
      return m;
    },
  });
  const result = await script.runInThisContext();
  console.log(result);  //  { bar: { hello: 'world' } }
})();拷贝