Node.js VM

May 5, 2025

CommonJS: vm.Script

从源码运行一个普通脚本：首先创建上下文对象，然后创建 vm.Script 对象，最后执行之。

上下文对象是通过使一个普通对象 “contextify” 来创建的，可通过 vm.isContext 判断一个对象是否是 contextified 对象。

import vm from "node:vm";

const script = new vm.Script(
    /*js*/ `
    function add(a, b) {
      // console 实际上是 globalThis.console 
      console.log("Called times: " + globalThis.count++);
      return a + b;
    }
    
    const x = add(1, 2);
    const y = add(3, 4);
    "eXpression";
`,
    {
        // 所有选项都是可选的
        filename: "evalmachine.<anonymous>",
        lineOffset: 0,
        columnOffset: 0,
    },
);

const context: vm.Context = vm.createContext(
    { count: 666, console },
    {
        name: "VM Context 0",
        origin: "file://test.js",
        codeGeneration: {
            strings: true,
            wasm: true,
        },
        microtaskMode: "afterEvaluate",
    },
);

// 返回表达式的值
const result = script.runInContext(context, {
    displayErrors: true,
    timeout: 1234,
});
console.log(result); // => "eXpression"

也可以从源码编译一个函数。

const parsingContext: vm.Context = vm.createContext(vm.constants.DONT_CONTEXTIFY);
parsingContext["console"] = console;
const fn: Function = vm.compileFunction(`return console.log(a + b)`, ["a", "b"] as const, {
    parsingContext, // 编译该函数的上下文对象
    contextExtensions: [],
    produceCachedData: false,
    cachedData: Buffer.from("nope"),
});

fn("Hello, ", "World!"); // => Hello, World!

vm.runInThisContext() 与 eval() 的区别在于 vm.runInThisContext() 无权访问本地作用域，但 eval() 则可以。
因此 vm.runInThisContext() 类似于 indirect eval() call

const vm = require("node: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'

上下文对象 “contextify”

所有在 Node.js 中执行的 JavaScript 代码都在“上下文”的范围内运行。根据 V8 嵌入器指南：

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

当传入对象来调用方法 vm.createContext() 时，contextObject 参数将用于包装 V8 上下文新实例的全局对象（如果 contextObject 是 undefined，则将在 contextified 之前从当前上下文创建一个新对象）。
此 V8 上下文为使用 node:vm 模块的方法运行的代码提供了一个隔离的全局环境，代码可以在其中运行。创建 V8 上下文并将其与外部上下文中的 contextObject 关联的过程就是“contextifying”对象。

contextifying 会给上下文中的 globalThis 值引入一些怪异之处。例如，它不能被冻结，并且它与外部上下文中的 contextObject 的引用不相等。

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

// `contextObject` 选项指定为 undefined，来使全局对象 contextified。
const context = vm.createContext();
console.log(vm.runInContext("globalThis", context) === context); // false
// 一个 contextified 的全局对象不能被冻结。
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

要创建一个具有普通全局对象的上下文，并在外部上下文中访问一个怪异之处较少的全局代理，可将 contextObject 参数指定为 vm.constants.DONT_CONTEXTIFY。

ESModule: vm.Module

vm.Module 表示 Module Record
vm.SourceTextModule Source Text Module Record
vm.SyntheticModule Synthetic Module Record

执行流程如下，与 ECMA262 一致。

备注：通过 node --experimental-vm-modules --experimental-strip-types demo.ts 运行下面的代码

import vm from "node:vm";
import type { ImportAttributes } from "node:module";

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

// Step 1
//
// 通过构造一个新的 `vm.SourceTextModule` 对象来创建一个模块。
// 这会解析提供的源代码文本，如果出现任何问题，则抛出一个 `SyntaxError`。
// 默认情况下，模块是在顶层上下文中创建的。但在这里，我们指定 `contextifiedObject` 作为此模块所属的上下文。
//
// 这里，我们尝试从模块 "foo" 中获取默认导出，并将其放入本地绑定 "secret" 中。
const bar: vm.Module = new vm.SourceTextModule(
    /*js*/ `
    import s from 'foo';
    s;
    print(s);
    export let abc = import.meta['abc']; // -> 123
    import("s")
`,
    {
        // 所有选项都是可选的
        context: contextifiedObject,
        identifier: "vm:module(0)",
        initializeImportMeta(meta, module: vm.SourceTextModule): void {
            meta["abc"] = 123; // <-
            console.assert(module === bar);
        },
        async importModuleDynamically(specifier: string, script, importAttributes): Promise<vm.Module> {
            console.log(specifier, script, importAttributes);
            throw new Error(`Dynamic import not supported: ${specifier}`);
        },
    },
);
// Cyclic Module Record [[Status]]
console.assert(bar.status === "unlinked");
console.assert(bar.context === contextifiedObject);
console.assert(bar.identifier === "vm:module(0)");
// Cyclic Module Record [[RequestedModules]]
console.log(bar.dependencySpecifiers); // => ["foo"]

// Step 2
//
// 将此模块导入的依赖项“链接”到它。
//
// 提供的链接回调（“linker”）接受两个参数：父模块（在本例中为 `bar`）和作为导入模块标识符的字符串。
// 回调应返回与提供的标识符相对应的模块，并满足 `module.link()` 中记录的某些要求。
//
// 如果返回的模块尚未开始链接，则将在返回的模块上调用相同的 linker 回调。
//
// 即使是没有依赖项的顶层模块也必须显式链接。但是，提供的回调永远不会被调用。
//
// link() 方法返回一个 Promise，当 linker 返回的所有 Promise 都解析时，该 Promise 将被解析。
//
// 注意：这是一个人为的例子，因为 linker 函数每次调用时都会创建一个新的 "foo" 模块。
// 在一个成熟的模块系统中，可能会使用缓存来避免重复的模块。

// Cyclic Module Record Link()
async function linker(
    specifier: string,
    referencingModule: vm.Module,
    extra: {
        attributes: ImportAttributes;
    },
): Promise<vm.Module> {
    if (specifier === "foo") {
        return new vm.SourceTextModule(
            /*js*/ `
            // "secret" 变量指的是我们在创建上下文时添加到 "contextifiedObject" 的全局变量。
            export default secret;`,
            // 这里使用 `contextifiedObject` 代替 `referencingModule.context` 也可以。
            { context: referencingModule.context },
        );
    }
    throw new Error(`Unable to resolve dependency: ${specifier}`);
}
await bar.link(linker);
console.assert(bar.status === "linked");

// Step 3
//
// 评估模块。evaluate() 方法返回一个 promise，该 promise 将在模块完成评估后 resolve。

// 打印 42。
await bar.evaluate();
console.assert(bar.status === "evaluated");
// GetModuleNamespace 返回 Module Namespace Object：包含所有导出绑定
console.log(bar.namespace); // => { abc: 123 }

if (bar.status === "errored") {
    // Cyclic Module Record [[EvaluationError]]
    console.error(bar.error);
}

合成模块（vm.SyntheticModule）的作用是提供一个通用接口，使非 JavaScript 源代码能够暴露于 ECMAScript 模块图中。

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

await module.link((specifier, referencingModule, { attributes }) => {});
await module.evaluate();
console.log(module.namespace); // => [Module: null prototype] { default: { a: 1 } }

下面纯翻译 https://github.com/nodejs/node/blob/main/doc/api/vm.md

异步任务和 Promise 的超时交互

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

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

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 });
// 这会在 'entering loop' *之前* 打印 (!)
console.log("done executing");

可以通过将 microtaskMode: 'afterEvaluate' 传递给创建 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()][] 不采用此选项。

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

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

编译 API 中对动态 `import()` 的支持

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

new vm.Script
vm.compileFunction()
new vm.SourceTextModule
vm.runInThisContext()
vm.runInContext()
vm.runInNewContext()
vm.createContext()

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

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

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

当 `importModuleDynamically` 为 `vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER` 时

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

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

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

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 不是新上下文中 Function 类的实例。
script.runInNewContext().then(console.log);

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

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

// 将 test.js 和 test.txt 写入当前脚本正在运行的目录。
writeFileSync(resolve(import.meta.dirname, "test.mjs"), 'export const filename = "./test.json";');
writeFileSync(resolve(import.meta.dirname, "test.json"), '{"hello": "world"}');

// 编译一个加载 test.mjs 然后加载 test.json 的脚本
// 就像脚本放置在同一目录中一样。
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);

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

要解析的模块将相对于传递给 vm.Script 或 vm.compileFunction() 的 filename 选项。该解析可以使用 filename，该 filename 是绝对路径或 URL 字符串。如果 filename 是既不是绝对路径也不是 URL 的字符串，或者如果它是未定义的，则解析将相对于进程的当前工作目录。在 vm.createContext() 的情况下，解析始终相对于当前工作目录，因为此选项仅在没有引用脚本或模块时使用。
对于解析为特定路径的任何给定 filename，一旦进程设法从该路径加载特定模块，结果可能会被缓存，并且随后从同一路径加载同一模块将返回相同的内容。如果 filename 是 URL 字符串，则如果它具有不同的搜索参数，则不会命中缓存。对于不是 URL 字符串的 filename，目前没有办法绕过缓存行为。

当 `importModuleDynamically` 是一个函数时

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

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

specifier {string} 传递给 import() 的说明符
referrer {vm.Script|Function|vm.SourceTextModule|Object} 对于 new vm.Script、vm.runInThisContext、vm.runInContext 和 vm.runInNewContext，referrer 是编译后的 vm.Script。对于 vm.compileFunction，它是编译后的 Function，对于 new vm.SourceTextModule，它是编译后的 vm.SourceTextModule，对于 vm.createContext()，它是上下文 Object。
importAttributes {Object} 传递给 optionsExpression 可选参数的 "with" 值，如果没有提供值，则为空对象。
phase {string} 动态导入的阶段（"source" 或 "evaluation"）。
返回值：{Module Namespace Object|vm.Module} 建议返回 vm.Module，以便利用错误跟踪，并避免包含 then 函数导出的命名空间的问题。

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); // 编译后的脚本
        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' } }

←Back to home

This work is licensed under CC BY-NC-SA 4.0