vm（虚拟机）#

源代码: lib/vm.js

vm 模块可在 V8 虚拟机上下文中编译和运行代码。 vm 模块不是安全的机制。不要使用它来运行不受信任的代码。

JavaScript 代码可以被立即编译并运行，也可以编译、保存并稍后运行。

一个常见的用例是在不同的 V8 上下文中运行代码。这意味着被调用的代码与调用的代码具有不同的全局对象。

可以通过使对象上下文隔离化来提供上下文。被调用的代码将上下文中的任何属性都视为全局变量。由调用的代码引起的对全局变量的任何更改都将会反映在上下文对象中。

const vm = require('vm');

const x = 1;

const context = { x: 2 };
vm.createContext(context); // 上下文隔离化对象。

const code = 'x += 40; var y = 17;';
// `x` and `y` 是上下文中的全局变量。
// 最初，x 的值为 2，因为这是 context.x 的值。
vm.runInContext(code, context);

console.log(context.x); // 42
console.log(context.y); // 17

console.log(x); // 1; y 没有定义。

vm.Script 类#

新增于: v0.3.1

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

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

版本历史

版本	变更
v10.6.0	The `produceCachedData` is deprecated in favour of `script.createCachedData()`.
v5.7.0	The `cachedData` and `produceCachedData` options are supported now.
v0.3.1	新增于: v0.3.1

code <string> 需要被解析的 JavaScript 代码。
options <Object> | <string>
- filename <string> 定义供脚本生成的堆栈跟踪信息所使用的文件名。默认值: 'evalmachine.<anonymous>'。
- lineOffset <number> 定义脚本生成的堆栈跟踪信息所显示的行号偏移。默认值: 0。
- columnOffset <number> 定义脚本生成的堆栈跟踪信息所显示的列号偏移。默认值: 0。
- cachedData <Buffer> | <TypedArray> | <DataView> 为源码提供一个可选的存有 V8 代码缓存数据的 Buffer、 TypedArray 或 TypedArray。如果提供了，则 cachedDataRejected 的值将会被设为要么为 true 要么为 false，这取决于 v8 引擎对数据的接受状况。
- produceCachedData <boolean> 当值为 true 且 cachedData 不存在的时候，V8 将会试图为 code 生成代码缓存数据。一旦成功，则一个有 V8 代码缓存数据的 Buffer 将会被生成和储存在返回的 vm.Script 实例的 cachedData 属性里。 cachedDataProduced 的值会被设置为 true 或者 false，这取决于代码缓存数据是否被成功生成。不推荐使用此选项，而应该使用 script.createCachedData()。默认值: false。
- importModuleDynamically <Function> 在调用 import() 时评估此模块期间调用。如果未指定此选项，则对 import() 的调用将拒绝 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING。此选项是实验的模块的 API 的一部分，不应被视为稳定。
  - specifier <string> 传给 import() 的说明符。
  - module <vm.Module>
  - 返回: <Module Namespace Object> | <vm.Module> 返回 vm.Module 以利用错误跟踪，并避免出现包含 then 函数导出的命名空间问题。

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

创建一个新的 vm.Script 对象只编译 code 但不会执行它。编译过的 vm.Script 此后可以被多次执行。 code 是不绑定于任何全局对象的，相反，它仅仅绑定于每次执行它的对象。

`script.createCachedData()`#

新增于: v10.6.0

返回: <Buffer>

创建一个可以被 Script 构造函数中 cachedData 选项使用的代码缓存。返回 Buffer。可以在任何时候不限次数地调用该方法。

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

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

const cacheWithoutX = script.createCachedData();

script.runInThisContext();

const cacheWithX = script.createCachedData();

`script.runInContext(contextifiedObject[, options])`#

版本历史

版本	变更
v6.3.0	The `breakOnSigint` option is supported now.
v0.3.1	新增于: v0.3.1

contextifiedObject <Object> 由 vm.createContext() 返回的上下文隔离化的对象。
options <Object>
- displayErrors <boolean> 当值为 true 的时候，假如在解析代码的时候发生错误 Error，引起错误的行将会被加入堆栈跟踪信息。默认值: true。
- timeout <integer> 定义在被终止执行之前此 code 被允许执行的最大毫秒数。假如执行被终止，将会抛出一个错误 Error。该值必须是严格正整数。
- breakOnSigint <boolean> 若值为 true，当收到 SIGINT (Ctrl+C)事件时，代码会被终止执行。此外，通过 process.on('SIGINT') 方法所设置的消息响应机制在代码被执行时会被屏蔽，但代码被终止后会被恢复。如果执行被终止，一个错误 Error 会被抛出。默认值: false。
返回: <any> 脚本中执行的最后一个语句的结果。

在指定的 contextifiedObject 中执行 vm.Script 对象中被编译后的代码并返回其结果。被执行的代码无法获取本地作用域。

以下的例子会编译一段代码，该代码会递增一个全局变量，给另外一个全局变量赋值。同时该代码被编译后会被多次执行。全局变量会被置于 context 对象内。

const vm = require('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);
// 打印: { animal: 'cat', count: 12, name: 'kitty' }

使用 timeout 或者 breakOnSigint 选项会导致若干新的事件循环以及对应的线程，这有一个非零的性能消耗。

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

版本历史

版本	变更
v14.6.0	The `microtaskMode` option is supported now.
v10.0.0	The `contextCodeGeneration` option is supported now.
v6.3.0	The `breakOnSigint` option is supported now.
v0.3.1	新增于: v0.3.1

contextObject <Object> 一个将会被上下文隔离化的对象。如果是 undefined, 则会生成一个新的对象。
options <Object>
- displayErrors <boolean> 当值为 true 的时候，假如在解析代码的时候发生错误 Error，引起错误的行将会被加入堆栈跟踪信息。默认值: true。
- timeout <integer> 定义在被终止执行之前此 code 被允许执行的最大毫秒数。假如执行被终止，将会抛出一个错误 Error。该值必须是严格正整数。
- breakOnSigint <boolean> 若值为 true，当收到 SIGINT (Ctrl+C)事件时，代码会被终止执行。此外，通过 process.on('SIGINT') 方法所设置的消息响应机制在代码被执行时会被屏蔽，但代码被终止后会被恢复。如果执行被终止，一个错误 Error 会被抛出。默认值: false。
- contextName <string> 新创建的上下文的人类可读名称。 默认值: 'VM Context i'，其中 i 是创建的上下文的升序数字索引。
- contextOrigin <string> 对应于新创建用于显示目的的上下文的原点。原点应格式化为类似一个 URL，但只包含协议，主机和端口（如果需要），例如 URL 对象的 url.origin 属性的值。最值得注意的是，此字符串应省略尾部斜杠，因为它表示路径。 默认值: ''。
- contextCodeGeneration <Object>
  - strings <boolean> 如果设置为 false，则对 eval 或函数构造函数（Function、 GeneratorFunction 等）的任何调用都将抛出 EvalError。默认值: true。
  - wasm <boolean> 如果设置为 false，则任何编译 WebAssembly 模块的尝试都将抛出 WebAssembly.CompileError。默认值: true。
- 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> 脚本中执行的最后一个语句的结果。

首先给指定的 contextObject 提供一个隔离的上下文, 再在此上下文中执行 vm.Script 中被编译的代码，最后返回结果。运行中的代码无法获取本地作用域。

以下的例子会编译一段代码，该代码会递增一个全局变量，给另外一个全局变量赋值。同时该代码被编译后会被多次执行。全局变量会被置于各个独立的 context 对象内。

const vm = require('vm');

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

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

console.log(contexts);
// 打印: [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }]

`script.runInThisContext([options])`#

新增于: v0.3.1

options <Object>
- displayErrors <boolean> 当值为 true 的时候，假如在解析代码的时候发生错误 Error，引起错误的行将会被加入堆栈跟踪信息。默认值: true。
- timeout <integer> 定义在被终止执行之前此 code 被允许执行的最大毫秒数。假如执行被终止，将会抛出一个错误 Error。该值必须是严格正整数。
- breakOnSigint <boolean> 若值为 true，当收到 SIGINT (Ctrl+C)事件时，代码会被终止执行。此外，通过 process.on('SIGINT') 方法所设置的消息响应机制在代码被执行时会被屏蔽，但代码被终止后会被恢复。如果执行被终止，一个错误 Error 会被抛出。默认值: false。
返回: <any> 脚本中执行的最后一个语句的结果。

在指定的 global 对象的上下文中执行 vm.Script 对象里被编译的代码并返回其结果。被执行的代码虽然无法获取本地作用域，但是能获取 global 对象。

以下的例子会编译一段代码，该代码会递增一个 global 变量。同时该代码被编译后会被多次执行。

const vm = require('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.measureMemory([options])`#

新增于: v13.10.0

稳定性: 1 - 实验

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

options <Object> Optional.
- mode <string> Either 'summary' or 'detailed'. In summary mode, only the memory measured for the main context will be returned. In detailed mode, the measure measured for all contexts known to the current V8 isolate will be returned. Default: 'summary'
- 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'
Returns: <Promise> If the memory is successfully measured the promise will resolve with an object containing information about the memory usage.

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.

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('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.Module 类#

新增于: v13.0.0, v12.16.0

稳定性: 1 - 实验

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

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.

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.

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

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.

const vm = require('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.

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

`module.error`#

<any>

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.

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

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

`module.evaluate([options])`#

options <Object>
- 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> If true, the execution will be terminated when SIGINT (Ctrl+C) is received. Existing handlers for the event that have been attached via process.on('SIGINT') will be disabled during script execution, but will continue to work after that. If execution is interrupted, an Error will be thrown. Default: false.
Returns: <Promise>

Evaluate the module.

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').

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

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

`module.link(linker)`#

linker <Function>
- specifier <string> The specifier of the requested module:
```
import foo from 'foo';
//              ^^^^^ the module specifier
```
- referencingModule <vm.Module> The Module object link() is called on.
- Returns: <vm.Module> | <Promise>
Returns: <Promise>

Link module dependencies. This method must be called before evaluation, and can only be called once per 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:

It must belong to the same context as the parent Module.
Its status must not be 'errored'.

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() 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.

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

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

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.

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

`module.namespace`#

<Object>

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

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() has not yet been called.
'linking': module.link() has been called, but not all Promises returned by the linker function have been resolved yet.
'linked': The module has been linked successfully, and all of its dependencies are linked, but module.evaluate() has not yet been called.
'evaluating': The module is being evaluated through a module.evaluate() on itself or a parent module.
'evaluated': The module has been successfully evaluated.
'errored': The module has been evaluated, but an exception was thrown.

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.

`module.identifier`#

<string>

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

vm.SourceTextModule 类#

新增于: v9.6.0

稳定性: 1 - 实验

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

继承自: <vm.Module>

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

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

code <string> JavaScript Module code to parse
options
- identifier <string> String used in stack traces. Default: 'vm:module(i)' where i is a context-specific ascending index.
- 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> The contextified object as returned by the vm.createContext() method, to compile and evaluate this Module in.
- lineOffset <integer> Specifies the line number offset that is displayed in stack traces produced by this Module. Default: 0.
- columnOffset <integer> Specifies the column number offset that is displayed in stack traces produced by this Module. Default: 0.
- initializeImportMeta <Function> Called during evaluation of this Module to initialize the import.meta.
  - meta <import.meta>
  - module <vm.SourceTextModule>
- 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> specifier passed to import()
  - module <vm.Module>
  - 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.

Creates a new SourceTextModule instance.

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.

const vm = require('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()`#

新增于: v13.7.0

Returns: <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.

// 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 类#

新增于: v13.0.0, v12.16.0

稳定性: 1 - 实验

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

继承自: <vm.Module>

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('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])`#

新增于: v13.0.0, v12.16.0

exportNames <string[]> Array of names that will be exported from the module.
evaluateCallback <Function> Called when the module is evaluated.
options
- identifier <string> String used in stack traces. Default: 'vm:module(i)' where i is a context-specific ascending index.
- context <Object> The contextified object as returned by the vm.createContext() method, to compile and evaluate this Module in.

Creates a new SyntheticModule instance.

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)`#

新增于: v13.0.0, v12.16.0

name <string> Name of the export to set.
value <any> The value to set the export to.

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.

const vm = require('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]])`#

版本历史

版本	变更
v14.3.0	Removal of `importModuleDynamically` due to compatibility issues.
v14.1.0, v13.14.0	The `importModuleDynamically` option is now supported.
v10.10.0	新增于: v10.10.0

code <string> 需要编译的函数体。
params <string[]> 包含所有函数参数的字符串数组。
options <Object>
- filename <string> 定义此脚本生成的堆栈跟踪信息中使用的文件名。 默认值: ''。
- lineOffset <number> 定义此脚本生成的堆栈跟踪信息中显示的行号偏移量。默认值: 0。
- columnOffset <number> 定义此脚本生成的堆栈跟踪中显示的列偏移量。 默认值: 0。
- cachedData <Buffer> | <TypedArray> | <DataView> 为源码提供一个 Buffer、 TypedArray 或 DataView 格式的 V8 代码缓存。
- produceCachedData <boolean> 定义是否需要生成新的缓存数据。默认值: false。
- parsingContext <Object> 编译函数的上下文隔离化的对象。
- contextExtensions <Object[]> 包含要在编译时应用的上下文扩展（包装当前范围的对象）的集合的数组。默认值: []。
返回: <Function>

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

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

版本历史

版本	变更
v14.6.0	The `microtaskMode` option is supported now.
v10.0.0	The first argument can no longer be a function.
v10.0.0	The `codeGeneration` option is supported now.
v0.3.1	新增于: v0.3.1

contextObject <Object>
options <Object>
- name <string> 新创建的上下文的人类可读名称。 默认值: 'VM Context i'，其中 i 是创建的上下文的升序数字索引。
- origin <string> 对应于新创建用于显示目的的上下文的原点。原点应格式化为类似一个 URL，但只包含协议，主机和端口（如果需要），例如 URL 对象的 url.origin 属性的值。最值得注意的是，此字符串应省略尾部斜杠，因为它表示路径。 默认值: ''。
- codeGeneration <Object>
  - strings <boolean> 如果设置为 false，则对 eval 或函数构造函数（Function、 GeneratorFunction 等）的任何调用都将抛出 EvalError。默认值: true。
  - wasm <boolean> 如果设置为 false，则任何编译 WebAssembly 模块的尝试都将抛出 WebAssembly.CompileError。默认值: true。
- 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> 上下文隔离化的沙盒。

给定一个 contextObject 对象， vm.createContext() 会设置此沙盒，从而让它具备在 vm.runInContext() 或者 script.runInContext() 中被使用的能力。在此类脚本中， contextObject 将会是全局对象，保留其所有现有属性，但还具有任何标准的全局对象具有的内置对象和函数。在 vm 模块运行的脚本之外，全局变量将会保持不变。

const vm = require('vm');

global.globalVar = 3;

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

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

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

console.log(global.globalVar);
// 打印: 3

如果未提供 contextObject（或者传入undefined），那么会返回一个全新的空的上下文隔离化对象。

vm.createContext() 主要是用于创建一个能运行多个脚本的上下文。比如说，在模拟一个网页浏览器时，此方法可以被用于创建一个单独的上下文来代表一个窗口的全局对象，然后所有的 <script> 标签都可以在这个上下文中运行。

通过 Inspector API 可以看到提供的上下文的 name 和 origin。

`vm.isContext(object)`#

新增于: v0.11.7

object <Object>
返回: <boolean>

当给定的 object 对象已经被 vm.createContext() 上下文隔离化，则返回 true。

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

版本历史

版本	变更
v6.3.0	The `breakOnSigint` option is supported now.
v0.3.1	新增于: v0.3.1

code <string> 将被编译和运行的 JavaScript 代码。
contextifiedObject <Object> 一个被上下文隔离化过的对象，会在 code 被编译和执行之后充当 global 对象。
options <Object> | <string>
- filename <string> 定义供脚本生成的堆栈跟踪信息所使用的文件名。默认值: 'evalmachine.<anonymous>'。
- lineOffset <number> 定义脚本生成的堆栈跟踪信息所显示的行号偏移。默认值: 0。
- columnOffset <number> 定义脚本生成的堆栈跟踪信息所显示的列号偏移。默认值: 0。
- displayErrors <boolean> 当值为 true 的时候，假如在解析代码的时候发生错误 Error，引起错误的行将会被加入堆栈跟踪信息。默认值: true。
- timeout <integer> 定义在被终止执行之前此 code 被允许执行的最大毫秒数。假如执行被终止，将会抛出一个错误 Error。该值必须是严格正整数。
- breakOnSigint <boolean> 若值为 true，当收到 SIGINT (Ctrl+C)事件时，代码会被终止执行。此外，通过 process.on('SIGINT') 方法所设置的消息响应机制在代码被执行时会被屏蔽，但代码被终止后会被恢复。如果执行被终止，一个错误 Error 会被抛出。默认值: false。
- cachedData <Buffer> | <TypedArray> | <DataView> 为源码提供一个可选的存有 V8 代码缓存数据的 Buffer、 TypedArray 或 TypedArray。如果提供了，则 cachedDataRejected 的值将会被设为要么为 true 要么为 false，这取决于 v8 引擎对数据的接受状况。
- produceCachedData <boolean> 当值为 true 且 cachedData 不存在的时候，V8 将会试图为 code 生成代码缓存数据。一旦成功，则一个有 V8 代码缓存数据的 Buffer 将会被生成和储存在返回的 vm.Script 实例的 cachedData 属性里。 cachedDataProduced 的值会被设置为 true 或者 false，这取决于代码缓存数据是否被成功生成。不推荐使用此选项，而应该使用 script.createCachedData()。默认值: false。
- importModuleDynamically <Function> 在调用 import() 时评估此模块期间调用。如果未指定此选项，则对 import() 的调用将拒绝 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING。此选项是实验的模块的 API 的一部分，不应被视为稳定。
  - specifier <string> 传给 import() 的说明符。
  - module <vm.Module>
  - 返回: <Module Namespace Object> | <vm.Module> 返回 vm.Module 以利用错误跟踪，并避免出现包含 then 函数导出的命名空间问题。
返回: <any> 脚本中执行的最后一个语句的结果。

vm.runInContext() 方法会编译 code，然后在指定的 contextifiedObject 的上下文里执行它并返回其结果。被执行的代码无法获取本地作用域。 contextifiedObject 必须是事先被 vm.createContext() 方法上下文隔离化过的对象。

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

以下例子使用一个单独的上下文隔离化过的对象来编译并运行几个不同的脚本：

const vm = require('vm');

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

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

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

版本历史

版本	变更
v14.6.0	The `microtaskMode` option is supported now.
v10.0.0	The `contextCodeGeneration` option is supported now.
v6.3.0	The `breakOnSigint` option is supported now.
v0.3.1	新增于: v0.3.1

code <string> 将被编译和运行的 JavaScript 代码。
contextObject <Object> 一个将会被上下文隔离化的对象。如果是 undefined, 则会生成一个新的对象。
options <Object> | <string>
- filename <string> 定义供脚本生成的堆栈跟踪信息所使用的文件名。默认值: 'evalmachine.<anonymous>'。
- lineOffset <number> 定义脚本生成的堆栈跟踪信息所显示的行号偏移。默认值: 0。
- columnOffset <number> 定义脚本生成的堆栈跟踪信息所显示的列号偏移。默认值: 0。
- displayErrors <boolean> 当值为 true 的时候，假如在解析代码的时候发生错误 Error，引起错误的行将会被加入堆栈跟踪信息。默认值: true。
- timeout <integer> 定义在被终止执行之前此 code 被允许执行的最大毫秒数。假如执行被终止，将会抛出一个错误 Error。该值必须是严格正整数。
- breakOnSigint <boolean> 若值为 true，当收到 SIGINT (Ctrl+C)事件时，代码会被终止执行。此外，通过 process.on('SIGINT') 方法所设置的消息响应机制在代码被执行时会被屏蔽，但代码被终止后会被恢复。如果执行被终止，一个错误 Error 会被抛出。默认值: false。
- contextName <string> 新创建的上下文的人类可读名称。 默认值: 'VM Context i'，其中 i 是创建的上下文的升序数字索引。
- contextOrigin <string> 对应于新创建用于显示目的的上下文的原点。原点应格式化为类似一个 URL，但只包含协议，主机和端口（如果需要），例如 URL 对象的 url.origin 属性的值。最值得注意的是，此字符串应省略尾部斜杠，因为它表示路径。 默认值: ''。
- contextCodeGeneration <Object>
  - strings <boolean> 如果设置为 false，则对 eval 或函数构造函数（Function、 GeneratorFunction 等）的任何调用都将抛出 EvalError。默认值: true。
  - wasm <boolean> 如果设置为 false，则任何编译 WebAssembly 模块的尝试都将抛出 WebAssembly.CompileError。默认值: true。
- cachedData <Buffer> | <TypedArray> | <DataView> 为源码提供一个可选的存有 V8 代码缓存数据的 Buffer、 TypedArray 或 TypedArray。如果提供了，则 cachedDataRejected 的值将会被设为要么为 true 要么为 false，这取决于 v8 引擎对数据的接受状况。
- produceCachedData <boolean> 当值为 true 且 cachedData 不存在的时候，V8 将会试图为 code 生成代码缓存数据。一旦成功，则一个有 V8 代码缓存数据的 Buffer 将会被生成和储存在返回的 vm.Script 实例的 cachedData 属性里。 cachedDataProduced 的值会被设置为 true 或者 false，这取决于代码缓存数据是否被成功生成。不推荐使用此选项，而应该使用 script.createCachedData()。默认值: false。
- importModuleDynamically <Function> 在调用 import() 时评估此模块期间调用。如果未指定此选项，则对 import() 的调用将拒绝 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING。此选项是实验的模块的 API 的一部分，不应被视为稳定。
  - specifier <string> 传给 import() 的说明符。
  - module <vm.Module>
  - 返回: <Module Namespace Object> | <vm.Module> 返回 vm.Module 以利用错误跟踪，并避免出现包含 then 函数导出的命名空间问题。
- 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> 脚本中执行的最后一个语句的结果。

vm.runInNewContext() 首先给指定的 contextObject（若为 undefined，则会新建一个 contextObject）提供一个隔离的上下文, 再在此上下文中执行编译的 code，最后返回结果。运行中的代码无法获取本地作用域。

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

以下的例子会编译一段代码，该代码会递增一个全局变量，给另外一个全局变量赋值。同时该代码被编译后会被多次执行。全局变量会被置于 contextObject 对象内。

const vm = require('vm');

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

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

`vm.runInThisContext(code[, options])`#

版本历史

版本	变更
v6.3.0	The `breakOnSigint` option is supported now.
v0.3.1	新增于: v0.3.1

code <string> 将被编译和运行的 JavaScript 代码。
options <Object> | <string>
- filename <string> 定义供脚本生成的堆栈跟踪信息所使用的文件名。默认值: 'evalmachine.<anonymous>'。
- lineOffset <number> 定义脚本生成的堆栈跟踪信息所显示的行号偏移。默认值: 0。
- columnOffset <number> 定义脚本生成的堆栈跟踪信息所显示的列号偏移。默认值: 0。
- displayErrors <boolean> 当值为 true 的时候，假如在解析代码的时候发生错误 Error，引起错误的行将会被加入堆栈跟踪信息。默认值: true。
- timeout <integer> 定义在被终止执行之前此 code 被允许执行的最大毫秒数。假如执行被终止，将会抛出一个错误 Error。该值必须是严格正整数。
- breakOnSigint <boolean> 若值为 true，当收到 SIGINT (Ctrl+C)事件时，代码会被终止执行。此外，通过 process.on('SIGINT') 方法所设置的消息响应机制在代码被执行时会被屏蔽，但代码被终止后会被恢复。如果执行被终止，一个错误 Error 会被抛出。默认值: false。
- cachedData <Buffer> | <TypedArray> | <DataView> 为源码提供一个可选的存有 V8 代码缓存数据的 Buffer、 TypedArray 或 TypedArray。如果提供了，则 cachedDataRejected 的值将会被设为要么为 true 要么为 false，这取决于 v8 引擎对数据的接受状况。
- produceCachedData <boolean> 当值为 true 且 cachedData 不存在的时候，V8 将会试图为 code 生成代码缓存数据。一旦成功，则一个有 V8 代码缓存数据的 Buffer 将会被生成和储存在返回的 vm.Script 实例的 cachedData 属性里。 cachedDataProduced 的值会被设置为 true 或者 false，这取决于代码缓存数据是否被成功生成。不推荐使用此选项，而应该使用 script.createCachedData()。默认值: false。
- importModuleDynamically <Function> 在调用 import() 时评估此模块期间调用。如果未指定此选项，则对 import() 的调用将拒绝 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING。此选项是实验的模块的 API 的一部分，不应被视为稳定。
  - specifier <string> 传给 import() 的说明符。
  - module <vm.Module>
  - 返回: <Module Namespace Object> | <vm.Module> 返回 vm.Module 以利用错误跟踪，并避免出现包含 then 函数导出的命名空间问题。
返回: <any> 脚本中执行的最后一个语句的结果。

vm.runInThisContext() 在当前的 global 对象的上下文中编译并执行 code，最后返回结果。运行中的代码无法获取本地作用域，但可以获取当前的 global 对象。

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

下面的例子演示了使用 vm.runInThisContext() 和 JavaScript 的 eval() 方法去执行相同的一段代码：

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

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

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

正因 vm.runInThisContext() 无法获取本地作用域，故 localVar 的值不变。相反，eval() 确实能获取本地作用域，所以 localVar 的值被改变了。如此看来， vm.runInThisContext() 更像是间接的执行 eval(), 就像 (0,eval)('code')。

示例：在 VM 中运行 HTTP Server#

在使用 script.runInThisContext() 或者 vm.runInThisContext() 时，目标代码是在当前的V8全局对象的上下文中执行的。被传入此虚拟机上下文的目标代码会有自己独立的作用域。

要想用 http 模块搭建一个简易的服务器，被传入的代码必须要么自己执行 require('http')，要么引用一个 http，比如：

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

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

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

  console.log('服务器运行在 http://127.0.0.1:8124/');
})`;

vm.runInThisContext(code)(require);

上述例子中的 require() 和导出它的上下文共享状态。这在运行未经认证的代码时可能会引入风险，比如在不理想的情况下修改上下文中的对象。

上下文隔离化一个对象意味着什么？#

所有用 Node.js 所运行的 JavaScript 代码都是在一个“上下文”的作用域中被执行的。根据 V8 嵌入式指南：

在 V8 中，一个上下文是一个执行环境，它允许分离的，无关的 JavaScript 应用在一个 V8 的单例中被运行。必须明确地指定用于运行所有 JavaScript 代码的上下文。

当调用 vm.createContext() 方法时， contextObject参数（如果 contextObject 为 undefined，则为新创建的对象）在内部与 V8 上下文的新实例相关联。该 V8 上下文提供了使用 vm 模块的方法运行的 code 以及可在其中运行的隔离的全局环境。创建 V8 上下文并将其与 contextObject 关联的过程是本文档所称的“上下文隔离化”对象。

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

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 解决后调度无限循环。调度的循环永远不会被超时中断：

const vm = require('vm');

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

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

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

const vm = require('vm');

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

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

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

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.

目录

vm（虚拟机）#

vm.Script 类#

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

script.createCachedData()#

script.runInContext(contextifiedObject[, options])#

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

script.runInThisContext([options])#

vm.measureMemory([options])#

vm.Module 类#

module.dependencySpecifiers#

module.error#

module.evaluate([options])#

module.link(linker)#

module.namespace#

module.status#

module.identifier#

vm.SourceTextModule 类#

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

sourceTextModule.createCachedData()#

vm.SyntheticModule 类#

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

syntheticModule.setExport(name, value)#

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

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

vm.isContext(object)#

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

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

vm.runInThisContext(code[, options])#

示例：在 VM 中运行 HTTP Server#

上下文隔离化一个对象意味着什么？#

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

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

`script.createCachedData()`#

`script.runInContext(contextifiedObject[, options])`#

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

`script.runInThisContext([options])`#

`vm.measureMemory([options])`#

`module.dependencySpecifiers`#

`module.error`#

`module.evaluate([options])`#

`module.link(linker)`#

`module.namespace`#

`module.status`#

`module.identifier`#

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

`sourceTextModule.createCachedData()`#

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

`syntheticModule.setExport(name, value)`#

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

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

`vm.isContext(object)`#

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

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

`vm.runInThisContext(code[, options])`#