Node.js模块处理机制

February 10, 2024April 6, 2025

本文不讨论具体的模块解析识和加载步骤，文档对此有详细描述。

CommonJS modules

require() 模块解析算法

CommonJS 模块执行前会被如下函数包装：（参见此处 Node.js 源码）

(function (
    exports: Module["exports"], // 指向 module.exports
    require: Require,
    module: Module, // 指向当前模块
    __filename: string,
    __dirname: string,
) {
    // 对 module.exports *同步*赋值，将值导出
    // module.exports 默认值是一个空对象，exports 仅当包装模块时是对这个对象的引用
    // 最终实际导出值是 module.exports，而不是 exports
});

为了验证之，测试 arguments 变量即可

// test.cjs
console.log(arguments);

require() 函数定义如下

interface Require {
    (id: string): any;
    resolve: RequireResolve;
    cache: Dict<NodeModule>;
    main: Module | undefined;
}

interface RequireResolve {
    (id: string, options?: { paths?: string[] | undefined }): string;
    paths(request: string): string[] | null;
}

interface Module {
    isPreloading: boolean;
    exports: any;
    require: Require;
    id: string;
    filename: string;
    loaded: boolean;
    children: Module[];
    path: string;
    paths: string[];
}

require() 函数对于相同输入 id，仅导入（执行）一次（在第一次时缓存，缓存到 require.cache 对象中），重复导入将得到相同的引用（在缓存 require.cache 中读取）。
注意 cjs 导入的结果是普通的 JavaScript 值，即导出和导入得到的值是相同的。（esm 则有不同）
此外 Node.js 内置模块都是可写的对象，这就允许它们被替换。而由于导入的是相同的引用，因此修改是立即可见的。

对于内置模块，如果不带 node: 前缀，也会尝试从 require.cache 中读取。
但若加上 node: 前缀则不会。因此 node: 前缀将保证能够获取到内置模块，但注意内置模块本身还是允许被修改的。

require("fs").write = (fd, str, cb) => {
    console.log(str + " <patched>");
};

require.cache.fs = {
    exports: {
        write() {
            console.log("fake!");
        },
    },
};

require.cache["node:fs"] = {
    exports: {
        write() {
            console.log("fake!");
        },
    },
};

// 确保得到内置模块，但内置模块本身允许被修改
const fs1 = require("node:fs");
fs1.write(1, "Hi, fs1", (err) => {}); // => Hi, fs1 <patched>

// 会先从缓存中读取
const fs2 = require("fs");
fs2.write(1, "Hi, fs2", (err) => {}); // => fake!

删除 require.cache 的键就可以令对应 id 重新加载导入

ECMAScript modules

ESM 模块除遵循语言规范外，还有 Node.js 的模块解析算法
另：mlly 库可能会有帮助

require() 导入的值与对应 module.exports 导出的值完全相同。
但在 ECMAScript 标准模块中，当导入整个模块作为一个对象时，得到是一个 Module 对象（module namespace object）。
该对象是普通的 JavaScript 对象，但其原型为 null，其 Symbol.toStringTag 键对应值为字符串 Module。
export 导出的对应键，在该对象中都是不可写的。

import * as m from "./esm.js";
const m = await import("./esm.js");

Object.getPrototypeOf(m) // => null

// m 相当于如下
{
    [Symbol.toStringTag]: 'Module'
    // ... 包含其它 export 导出的对应键
}

Node.js 模块的 ESM 导出，是命名导出所有 API，并将 CommonJS 导出值以 default 导出。
这种方式导出方式就很方便了，因为：

// 无需（当然也可以）
import * as fs from "fs";
// 只需（因为有 default 导出）
import fs from "fs";

以第一种导入方式时，根据 ESM 规范，该对象的键当然是不可写的。
第二种方式导入的相当于 require() 返回值，因此其键可写。

default 导出值就是 CommonJS 导出值。因此只有修改 default 导出值，才能在 ESM 环境中修改内置模块，
但需调用特殊的 syncBuiltinESMExports 函数，才能传播修改。

import fs, { readFileSync } from "node:fs";
import { syncBuiltinESMExports } from "node:module";
import { Buffer } from "node:buffer";

fs.readFileSync = () => Buffer.from("Hello, ESM");
syncBuiltinESMExports();

fs.readFileSync === readFileSync; // => true

对于我们自己编写的 CJS 模块，根据文档：
ESM 环境导入 CJS 模块时，module.exports 对象提供为 default 导出。为了更好的兼容性，会静态分析来提供命名导出。

ESM 与 CJS 互操性

Node.js 需要确定脚本是 ESM 还是 CJS，参见此处。需要注意 Node.js 对这些特性的支持版本。

ESM 环境没有 require 函数，通过以下方法得到：

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);

目前，Node.js 已实验性支持通过 require() 加载 ES 模块
模块加载结果与 await import() 一致。限制条件为 ES 模块必须完全同步，即不含 top-level await

Typescript

moduleResolution 选项

module 选项决定编译器输出的模块类型，moduleResolution 决定如何解析输入的模块。

对于现代 Node.js 应用，使用 tsc 编译时，指定为 nodenext 即可。此时会仿照 Node.js 模块解析方式。
对于浏览器环境，往往真正是由其它 bundler 来解析依赖，因此指定为 bundler。此时允许省略文件名后缀。

allowSyntheticDefaultImports 和 esModuleInterop 选项

typescript 本身是根据 declaration 来识别导出的，这就可能导致 default 导入出现问题。

这些选项可处理此问题，具体参见handbook和对应文档。

bundler

在 ESM 规范中，import 不能省略文件名后缀（毕竟浏览器是网络请求，而不是本地文件系统），但很多 bundler 在解析 import 时并不会这么严格。

rollup

见 @rollup/plugin-commonjs 包 extensions 选项

webpack

见 resolve.extensions

esbuild

见 resolve extensions

CommonJS modules 实现

WIP

/lib/internal/modules/cjs/loader.js

/**
 * Create a new module instance.
 * @param {string} id
 * @param {Module} parent
 */
function Module(id = "", parent) {
    this.id = id;
    this.path = path.dirname(id);
    setOwnProperty(this, "exports", {});
    this[kModuleParent] = parent;
    updateChildren(parent, this, false);
    this.filename = null;
    this.loaded = false;
    this.children = [];
}

/** @type {Record<string, Module>} */
Module._cache = { __proto__: null };
/** @type {Record<string, string>} */
Module._pathCache = { __proto__: null };
/** @type {Record<string, (module: Module, filename: string) => void>} */
Module._extensions = { __proto__: null };
/** @type {string[]} */
let modulePaths = [];
/** @type {string[]} */
Module.globalPaths = [];

let patched = false;

/**
 * Add the CommonJS wrapper around a module's source code.
 * @param {string} script Module source code
 */
let wrap = function (script) {
    // eslint-disable-line func-style
    return Module.wrapper[0] + script + Module.wrapper[1];
};

const wrapper = ["(function (exports, require, module, __filename, __dirname) { ", "\n});"];

let wrapperProxy = new Proxy(wrapper, {
    __proto__: null,

    set(target, property, value, receiver) {
        patched = true;
        return ReflectSet(target, property, value, receiver);
    },

    defineProperty(target, property, descriptor) {
        patched = true;
        return ObjectDefineProperty(target, property, descriptor);
    },
});

ObjectDefineProperty(Module, "wrap", {
    __proto__: null,
    get() {
        return wrap;
    },

    set(value) {
        patched = true;
        wrap = value;
    },
});

ObjectDefineProperty(Module, "wrapper", {
    __proto__: null,
    get() {
        return wrapperProxy;
    },

    set(value) {
        patched = true;
        wrapperProxy = value;
    },
});

/lib/internal/modules/cjs/loader.js

/**
 * Wraps the given content in a script and runs it in a new context.
 * @param {string} filename The name of the file being loaded
 * @param {string} content The content of the file being loaded
 * @param {Module|undefined} cjsModuleInstance The CommonJS loader instance
 * @param {'commonjs'|undefined} format Intended format of the module.
 */
function wrapSafe(filename, content, cjsModuleInstance, format) {
    assert(format !== "module", "ESM should be handled in loadESMFromCJS()");
    const hostDefinedOptionId = vm_dynamic_import_default_internal;
    const importModuleDynamically = vm_dynamic_import_default_internal;
    if (patched) {
        const wrapped = Module.wrap(content);
        const script = makeContextifyScript(
            wrapped, // code
            filename, // filename
            0, // lineOffset
            0, // columnOffset
            undefined, // cachedData
            false, // produceCachedData
            undefined, // parsingContext
            hostDefinedOptionId, // hostDefinedOptionId
            importModuleDynamically, // importModuleDynamically
        );

        // Cache the source map for the module if present.
        const { sourceMapURL } = script;
        if (sourceMapURL) {
            maybeCacheSourceMap(filename, content, cjsModuleInstance, false, undefined, sourceMapURL);
        }

        return {
            __proto__: null,
            function: runScriptInThisContext(script, true, false), // 关键函数
            sourceMapURL,
        };
    }

    let shouldDetectModule = false;
    if (format !== "commonjs") {
        if (cjsModuleInstance?.[kIsMainSymbol]) {
            // For entry points, format detection is used unless explicitly disabled.
            shouldDetectModule = getOptionValue("--experimental-detect-module");
        } else {
            // For modules being loaded by `require()`, if require(esm) is disabled,
            // don't try to reparse to detect format and just throw for ESM syntax.
            shouldDetectModule = getOptionValue("--experimental-require-module");
        }
    }
    const result = compileFunctionForCJSLoader(content, filename, false /* is_sea_main */, shouldDetectModule);

    // Cache the source map for the module if present.
    if (result.sourceMapURL) {
        maybeCacheSourceMap(filename, content, cjsModuleInstance, false, undefined, result.sourceMapURL);
    }

    return result;
}

/**
 * Run the file contents in the correct scope or sandbox. Expose the correct helper variables (`require`, `module`,
 * `exports`) to the file. Returns exception, if any.
 * @param {string} content The source code of the module
 * @param {string} filename The file path of the module
 * @param {
 *    'module'|'commonjs'|'commonjs-typescript'|'module-typescript'
 * } format Intended format of the module.
 */
Module.prototype._compile = function (content, filename, format) {
    // 注：node22 通过 @swc/wasm-typescript 支持typescript，这里做类型擦除
    if (format === "commonjs-typescript" || format === "module-typescript" || format === "typescript") {
        content = stripTypeScriptModuleTypes(content, filename);
        switch (format) {
            case "commonjs-typescript": {
                format = "commonjs";
                break;
            }
            case "module-typescript": {
                format = "module";
                break;
            }
            // If the format is still unknown i.e. 'typescript', detect it in
            // wrapSafe using the type-stripped source.
            default:
                format = undefined;
                break;
        }
    }

    let redirects;

    let compiledWrapper;
    if (format !== "module") {
        // 默认当作 commonjs 执行
        // 通过 wrapSafe，将给定源码生成函数
        const result = wrapSafe(filename, content, this, format);
        compiledWrapper = result.function;
        if (result.canParseAsESM) {
            format = "module";
        }
    }

    if (format === "module") {
        loadESMFromCJS(this, filename, format, content);
        return;
    }

    // 创建包装函数所需参数
    const dirname = path.dirname(filename);
    const require = makeRequireFunction(this, redirects);
    let result;
    const exports = this.exports;
    const thisValue = exports;
    const module = this;
    if (requireDepth === 0) {
        statCache = new SafeMap();
    }
    setHasStartedUserCJSExecution();
    this[kIsExecuting] = true;
    if (this[kIsMainSymbol] && getOptionValue("--inspect-brk")) {
        const { callAndPauseOnStart } = internalBinding("inspector");
        result = callAndPauseOnStart(compiledWrapper, thisValue, exports, require, module, filename, dirname);
    } else {
        result = ReflectApply(compiledWrapper, thisValue, [exports, require, module, filename, dirname]);
    }
    this[kIsExecuting] = false;
    if (requireDepth === 0) {
        statCache = null;
    }
    return result;
};

/lib/internal/vm.js

/**
 * Runs a script in the current context.
 * Internal version of `vm.Script.prototype.runInThisContext()` which skips argument validation.
 * @param {ReturnType<makeContextifyScript>} script - The script to run.
 * @param {boolean} displayErrors - Whether to display errors.
 * @param {boolean} breakOnFirstLine - Whether to break on the first line.
 */
function runScriptInThisContext(script, displayErrors, breakOnFirstLine) {
    return ReflectApply(runInContext, script, [
        null, // sandbox - use current context
        -1, // timeout
        displayErrors, // displayErrors
        false, // breakOnSigint
        breakOnFirstLine, // breakOnFirstLine
    ]);
}

/lib/internal/vm.js

function runInContext(code, contextifiedObject, options) {
    validateContext(contextifiedObject);
    if (typeof options === "string") {
        options = {
            filename: options,
            [kParsingContext]: contextifiedObject,
        };
    } else {
        options = { ...options, [kParsingContext]: contextifiedObject };
    }
    return createScript(code, options).runInContext(contextifiedObject, options);
}

function createScript(code, options) {
    return new Script(code, options);
}

class Script extends ContextifyScript {
    // 省略
}

ContextifyScript 本质是一个 c++ 对象

cpp

class ContextifyScript final : CPPGC_MIXIN(ContextifyScript) {
 public:
  SET_CPPGC_NAME(ContextifyScript)
  void Trace(cppgc::Visitor* visitor) const final;

  ContextifyScript(Environment* env, v8::Local<v8::Object> object);
  ~ContextifyScript() override;

  v8::Local<v8::UnboundScript> unbound_script() const;
  void set_unbound_script(v8::Local<v8::UnboundScript>);

  static void CreatePerIsolateProperties(IsolateData* isolate_data,
                                         v8::Local<v8::ObjectTemplate> target);
  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
  static ContextifyScript* New(Environment* env, v8::Local<v8::Object> object);
  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
  static bool InstanceOf(Environment* env, const v8::Local<v8::Value>& args);
  static void CreateCachedData(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void RunInContext(const v8::FunctionCallbackInfo<v8::Value>& args);
  static bool EvalMachine(v8::Local<v8::Context> context,
                          Environment* env,
                          const int64_t timeout,
                          const bool display_errors,
                          const bool break_on_sigint,
                          const bool break_on_first_line,
                          v8::MicrotaskQueue* microtask_queue,
                          const v8::FunctionCallbackInfo<v8::Value>& args);

 private:
  v8::TracedReference<v8::UnboundScript> script_;
};

ECMAScript modules 实现

/lib/internal/modules/esm/loader.js

function createModuleLoader() {
    let customizations = null;
    // Don't spawn a new worker if custom loaders are disabled. For instance, if
    // we're already in a worker thread created by instantiating
    // CustomizedModuleLoader; doing so would cause an infinite loop.
    if (!forceDefaultLoader()) {
        const userLoaderPaths = getOptionValue("--experimental-loader");
        if (userLoaderPaths.length > 0) {
            if (!emittedLoaderFlagWarning) {
                const readableURIEncode = (string) =>
                    ArrayPrototypeReduce(
                        [
                            [/'/g, "%27"], // We need to URL-encode the single quote as it's the delimiter for the --import flag.
                            [/%22/g, '"'], // We can decode the double quotes to improve readability.
                            [/%2F/gi, "/"], // We can decode the slashes to improve readability.
                        ],
                        (str, { 0: regex, 1: replacement }) =>
                            RegExpPrototypeSymbolReplace(hardenRegExp(regex), str, replacement),
                        encodeURIComponent(string),
                    );
                process.emitWarning(
                    "`--experimental-loader` may be removed in the future; instead use `register()`:\n" +
                        `--import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; ${ArrayPrototypeJoin(
                            ArrayPrototypeMap(
                                userLoaderPaths,
                                (loader) =>
                                    `register(${readableURIEncode(JSONStringify(loader))}, pathToFileURL("./"))`,
                            ),
                            "; ",
                        )};'`,
                    "ExperimentalWarning",
                );
                emittedLoaderFlagWarning = true;
            }
            customizations = new CustomizedModuleLoader();
        }
    }

    return new ModuleLoader(customizations);
}

注册(Register): 可选步骤，用于注册自定义加载器。通过 module.exports.register 或命令行参数 --experimental-loader 实现。自定义加载器可以拦截和修改默认的加载流程。
解析(Resolve): 将模块标识符（specifier）解析为模块的 URL。核心函数包括：
- ModuleLoader.resolve(specifier, parentURL, importAttributes): 入口函数，处理自定义 resolve 钩子。
- ModuleLoader.resolveSync(specifier, parentURL, importAttributes): 同步版本，用于 import.meta.resolve 和在 CJS 中 require ESM。
- ModuleLoader.defaultResolve(originalSpecifier, parentURL, importAttributes): 默认的同步解析逻辑，如果没有自定义钩子则使用它。内部使用 internal/modules/esm/resolve.defaultResolve。
- ModuleLoader.#resolveAndMaybeBlockOnLoaderThread: 在同步解析中处理异步钩子，必要时阻塞主线程。
加载(Load): 根据解析得到的 URL 加载模块的源代码。核心函数包括：
- ModuleLoader.load(url, context): 入口函数，处理自定义 load 钩子。
- ModuleLoader.#loadSync(url, context): 同步版本，用于在 CJS 中 require ESM。
- ModuleLoader.#loadAndMaybeBlockOnLoaderThread: 在同步加载中处理异步钩子，必要时阻塞主线程。
- 默认加载函数：internal/modules/esm/load defaultLoad (异步) 和 internal/modules/esm/load defaultLoadSync (同步)。
翻译(Translate): 将加载的源代码转换为可执行的模块包装对象（ModuleWrap）。核心函数：
- ModuleLoader.#translate(url, format, source, isMain): 根据模块格式选择合适的翻译器进行转换。翻译器定义在 internal/modules/esm/translators 中。
实例化(Instantiate)和求值(Evaluate): 创建模块实例，执行模块代码，并将导出的值存储在命名空间对象中。核心类：
- ModuleJob: 异步加载和执行模块。
- ModuleJobSync: 同步加载和执行模块，用于在 CJS 中 require ESM。
定义在 /lib/internal/modules/esm/module_job.js
缓存(Cache): Node.js 会缓存已解析和加载的模块。ModuleLoader 的 resolveCache 和 loadCache 属性用于存储缓存结果。

Caution

以最新源码为准，贴出来的可能过时了

/lib/internal/modules/esm/module_job.js

/* A ModuleJob tracks the loading of a single Module, and the ModuleJobs of
 * its dependencies, over time. */
class ModuleJob extends ModuleJobBase {
    #loader = null;

    /**
     * @param {ModuleLoader} loader The ESM loader.
     * @param {string} url URL of the module to be wrapped in ModuleJob.
     * @param {ImportAttributes} importAttributes Import attributes from the import statement.
     * @param {ModuleWrap|Promise<ModuleWrap>} moduleOrModulePromise Translated ModuleWrap for the module.
     * @param {boolean} isMain Whether the module is the entry point.
     * @param {boolean} inspectBrk Whether this module should be evaluated with the
     *                             first line paused in the debugger (because --inspect-brk is passed).
     * @param {boolean} isForRequireInImportedCJS Whether this is created for require() in imported CJS.
     */
    constructor(
        loader,
        url,
        importAttributes = { __proto__: null },
        moduleOrModulePromise,
        isMain,
        inspectBrk,
        isForRequireInImportedCJS = false,
    ) {
        super(url, importAttributes, isMain, inspectBrk);
        this.#loader = loader;

        // Expose the promise to the ModuleWrap directly for linking below.
        if (isForRequireInImportedCJS) {
            this.module = moduleOrModulePromise;
            assert(this.module instanceof ModuleWrap);
            this.modulePromise = PromiseResolve(this.module);
        } else {
            this.modulePromise = moduleOrModulePromise;
        }
        //! 注意：ModuleWrap 由 C++ 实现，参见下文
        //! this.module 指向一个 C++ 对象

        // Promise for the list of all dependencyJobs.
        this.linked = this._link();
        // This promise is awaited later anyway, so silence
        // 'unhandled rejection' warnings.
        PromisePrototypeThen(this.linked, undefined, noop);

        // instantiated == deep dependency jobs wrappers are instantiated,
        // and module wrapper is instantiated.
        this.instantiated = undefined;
    }

    /**
     * Iterates the module requests and links with the loader.
     * @returns {Promise<ModuleJob[]>} Dependency module jobs.
     */
    async _link() {
        this.module = await this.modulePromise;
        assert(this.module instanceof ModuleWrap);

        const moduleRequests = this.module.getModuleRequests();
        // Explicitly keeping track of dependency jobs is needed in order
        // to flatten out the dependency graph below in `_instantiate()`,
        // so that circular dependencies can't cause a deadlock by two of
        // these `link` callbacks depending on each other.
        // Create an ArrayLike to avoid calling into userspace with `.then`
        // when returned from the async function.
        const dependencyJobs = Array(moduleRequests.length);
        ObjectSetPrototypeOf(dependencyJobs, null);

        // Specifiers should be aligned with the moduleRequests array in order.
        const specifiers = Array(moduleRequests.length);
        const modulePromises = Array(moduleRequests.length);
        // Iterate with index to avoid calling into userspace with `Symbol.iterator`.
        for (let idx = 0; idx < moduleRequests.length; idx++) {
            const { specifier, attributes } = moduleRequests[idx];
            // TODO(joyeecheung): resolve all requests first, then load them in another
            // loop so that hooks can pre-fetch sources off-thread.
            const dependencyJobPromise = this.#loader.getModuleJobForImport(specifier, this.url, attributes);
            const modulePromise = PromisePrototypeThen(dependencyJobPromise, (job) => {
                debug(`async link() ${this.url} -> ${specifier}`, job);
                dependencyJobs[idx] = job;
                return job.modulePromise;
            });
            modulePromises[idx] = modulePromise;
            specifiers[idx] = specifier;
        }

        const modules = await SafePromiseAllReturnArrayLike(modulePromises);
        this.module.link(specifiers, modules);

        return dependencyJobs;
    }

    instantiate() {
        if (this.instantiated === undefined) {
            this.instantiated = this._instantiate();
        }
        return this.instantiated;
    }

    async _instantiate() {
        const jobsInGraph = new SafeSet();
        const addJobsToDependencyGraph = async (moduleJob) => {
            debug(`async addJobsToDependencyGraph() ${this.url}`, moduleJob);

            if (jobsInGraph.has(moduleJob)) {
                return;
            }
            jobsInGraph.add(moduleJob);
            const dependencyJobs = await moduleJob.linked;
            return SafePromiseAllReturnVoid(dependencyJobs, addJobsToDependencyGraph);
        };
        await addJobsToDependencyGraph(this);

        try {
            if (!hasPausedEntry && this.inspectBrk) {
                hasPausedEntry = true;
                const initWrapper = internalBinding("inspector").callAndPauseOnStart;
                initWrapper(this.module.instantiate, this.module);
            } else {
                this.module.instantiate();
            }
        } catch (e) {
            decorateErrorStack(e);
            // TODO(@bcoe): Add source map support to exception that occurs as result
            // of missing named export. This is currently not possible because
            // stack trace originates in module_job, not the file itself. A hidden
            // symbol with filename could be set in node_errors.cc to facilitate this.
            if (
                !getSourceMapsSupport().enabled &&
                StringPrototypeIncludes(e.message, " does not provide an export named")
            ) {
                const splitStack = StringPrototypeSplit(e.stack, "\n");
                const parentFileUrl = RegExpPrototypeSymbolReplace(/:\d+$/, splitStack[0], "");
                const { 1: childSpecifier, 2: name } = RegExpPrototypeExec(
                    /module '(.*)' does not provide an export named '(.+)'/,
                    e.message,
                );
                const { url: childFileURL } = await this.#loader.resolve(childSpecifier, parentFileUrl, kEmptyObject);
                let format;
                try {
                    // This might throw for non-CommonJS modules because we aren't passing
                    // in the import attributes and some formats require them; but we only
                    // care about CommonJS for the purposes of this error message.
                    ({ format } = await this.#loader.load(childFileURL));
                } catch {
                    // Continue regardless of error.
                }

                if (format === "commonjs") {
                    const importStatement = splitStack[1];
                    // TODO(@ctavan): The original error stack only provides the single
                    // line which causes the error. For multi-line import statements we
                    // cannot generate an equivalent object destructuring assignment by
                    // just parsing the error stack.
                    const oneLineNamedImports = RegExpPrototypeExec(/{.*}/, importStatement);
                    const destructuringAssignment =
                        oneLineNamedImports && RegExpPrototypeSymbolReplace(/\s+as\s+/g, oneLineNamedImports, ": ");
                    e.message =
                        `Named export '${name}' not found. The requested module` +
                        ` '${childSpecifier}' is a CommonJS module, which may not support` +
                        " all module.exports as named exports.\nCommonJS modules can " +
                        "always be imported via the default export, for example using:" +
                        `\n\nimport pkg from '${childSpecifier}';\n${
                            destructuringAssignment ? `const ${destructuringAssignment} = pkg;\n` : ""
                        }`;
                    const newStack = StringPrototypeSplit(e.stack, "\n");
                    newStack[3] = `SyntaxError: ${e.message}`;
                    e.stack = ArrayPrototypeJoin(newStack, "\n");
                }
            }
            throw e;
        }

        for (const dependencyJob of jobsInGraph) {
            // Calling `this.module.instantiate()` instantiates not only the
            // ModuleWrap in this module, but all modules in the graph.
            dependencyJob.instantiated = resolvedPromise;
        }
    }

    runSync() {
        assert(this.module instanceof ModuleWrap);
        if (this.instantiated !== undefined) {
            return { __proto__: null, module: this.module };
        }

        this.module.instantiate();
        this.instantiated = PromiseResolve();
        const timeout = -1;
        const breakOnSigint = false;
        setHasStartedUserESMExecution();
        this.module.evaluate(timeout, breakOnSigint);
        return { __proto__: null, module: this.module };
    }

    async run(isEntryPoint = false) {
        await this.instantiate();
        if (isEntryPoint) {
            globalThis[entry_point_module_private_symbol] = this.module;
        }
        const timeout = -1;
        const breakOnSigint = false;
        setHasStartedUserESMExecution();
        try {
            await this.module.evaluate(timeout, breakOnSigint);
        } catch (e) {
            if (e?.name === "ReferenceError" && isCommonJSGlobalLikeNotDefinedError(e.message)) {
                e.message += " in ES module scope";

                if (StringPrototypeStartsWith(e.message, "require ")) {
                    e.message += ", you can use import instead";
                }

                const packageConfig =
                    StringPrototypeStartsWith(this.module.url, "file://") &&
                    RegExpPrototypeExec(/\.js(\?[^#]*)?(#.*)?$/, this.module.url) !== null &&
                    require("internal/modules/package_json_reader").getPackageScopeConfig(this.module.url);
                if (packageConfig.type === "module") {
                    e.message +=
                        "\nThis file is being treated as an ES module because it has a " +
                        `'.js' file extension and '${packageConfig.pjsonPath}' contains ` +
                        '"type": "module". To treat it as a CommonJS script, rename it ' +
                        "to use the '.cjs' file extension.";
                }
            }
            throw e;
        }
        return { __proto__: null, module: this.module };
    }
}

js 侧实现的 ModuleJob 类的主要职责是：

链接 (Linking): 解析模块的依赖项，创建 ModuleJob 实例来加载这些依赖项，并将它们与当前模块链接起来。
实例化 (Instantiation): 准备模块及其依赖项的执行环境。
执行 (Execution): 实际运行模块的代码。

观察源码易知，ModuleWrap 是真正由 v8 执行模块的类，本质是一个 c++ 对象。（下面只给出头文件源码）

它在 Node.js 内部表示一个 V8 模块。它是一个包装器，用于封装 V8 引擎中的模块对象。它提供了与 V8 交互的接口，允许 Node.js 控制模块的生命周期。

关键方法：

getModuleRequests(): 返回模块的导入请求（依赖项）。
link(specifiers, modules): 将模块的依赖项（其他 ModuleWrap 实例）链接到当前模块。这在 V8 内部创建模块之间的依赖关系图。
instantiate(): 在 V8 中实例化模块。这会准备模块的执行环境，例如创建作用域和绑定变量。
evaluate(timeout, breakOnSigint): 在 V8 中执行模块的代码。

/src/module_wrap.h

class ModuleWrap : public BaseObject {
 public:
  enum InternalFields {
    kModuleSlot = BaseObject::kInternalFieldCount,
    kURLSlot,
    kSyntheticEvaluationStepsSlot,
    kContextObjectSlot,  // Object whose creation context is the target Context
    kInternalFieldCount
  };

  static void CreatePerIsolateProperties(IsolateData* isolate_data,
                                         v8::Local<v8::ObjectTemplate> target);
  static void CreatePerContextProperties(v8::Local<v8::Object> target,
                                         v8::Local<v8::Value> unused,
                                         v8::Local<v8::Context> context,
                                         void* priv);
  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
  static void HostInitializeImportMetaObjectCallback(
      v8::Local<v8::Context> context,
      v8::Local<v8::Module> module,
      v8::Local<v8::Object> meta);

  void MemoryInfo(MemoryTracker* tracker) const override {
    tracker->TrackField("resolve_cache", resolve_cache_);
  }

  v8::Local<v8::Context> context() const;
  v8::Maybe<bool> CheckUnsettledTopLevelAwait();

  SET_MEMORY_INFO_NAME(ModuleWrap)
  SET_SELF_SIZE(ModuleWrap)

  bool IsNotIndicativeOfMemoryLeakAtExit() const override {
    // XXX: The garbage collection rules for ModuleWrap are *super* unclear.
    // Do these objects ever get GC'd? Are we just okay with leaking them?
    return true;
  }

  static v8::Local<v8::PrimitiveArray> GetHostDefinedOptions(
      v8::Isolate* isolate, v8::Local<v8::Symbol> symbol);

  // When user_cached_data is not std::nullopt, use the code cache if it's not
  // nullptr, otherwise don't use code cache.
  // TODO(joyeecheung): when it is std::nullopt, use on-disk cache
  // See: https://github.com/nodejs/node/issues/47472
  static v8::MaybeLocal<v8::Module> CompileSourceTextModule(
      Realm* realm,
      v8::Local<v8::String> source_text,
      v8::Local<v8::String> url,
      int line_offset,
      int column_offset,
      v8::Local<v8::PrimitiveArray> host_defined_options,
      std::optional<v8::ScriptCompiler::CachedData*> user_cached_data,
      bool* cache_rejected);

  static void CreateRequiredModuleFacade(
      const v8::FunctionCallbackInfo<v8::Value>& args);

 private:
  ModuleWrap(Realm* realm,
             v8::Local<v8::Object> object,
             v8::Local<v8::Module> module,
             v8::Local<v8::String> url,
             v8::Local<v8::Object> context_object,
             v8::Local<v8::Value> synthetic_evaluation_step);
  ~ModuleWrap() override;

  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void GetModuleRequests(
      const v8::FunctionCallbackInfo<v8::Value>& args);
  static void InstantiateSync(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void EvaluateSync(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void GetNamespaceSync(const v8::FunctionCallbackInfo<v8::Value>& args);

  static void Link(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void Instantiate(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void Evaluate(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void GetNamespace(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void GetStatus(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void GetError(const v8::FunctionCallbackInfo<v8::Value>& args);

  static void SetImportModuleDynamicallyCallback(
      const v8::FunctionCallbackInfo<v8::Value>& args);
  static void SetInitializeImportMetaObjectCallback(
      const v8::FunctionCallbackInfo<v8::Value>& args);
  static v8::MaybeLocal<v8::Value> SyntheticModuleEvaluationStepsCallback(
      v8::Local<v8::Context> context, v8::Local<v8::Module> module);
  static void SetSyntheticExport(
      const v8::FunctionCallbackInfo<v8::Value>& args);
  static void CreateCachedData(const v8::FunctionCallbackInfo<v8::Value>& args);

  static v8::MaybeLocal<v8::Module> ResolveModuleCallback(
      v8::Local<v8::Context> context,
      v8::Local<v8::String> specifier,
      v8::Local<v8::FixedArray> import_attributes,
      v8::Local<v8::Module> referrer);
  static ModuleWrap* GetFromModule(node::Environment*, v8::Local<v8::Module>);

  v8::Global<v8::Module> module_;
  std::unordered_map<std::string, v8::Global<v8::Object>> resolve_cache_;
  contextify::ContextifyContext* contextify_context_ = nullptr;
  bool synthetic_ = false;
  int module_hash_;
};

内部模块机制

这里首先快速介绍一下 C++ API，具体Node.js 相关文档

v8::Isolate 隔离是一个 v8 虚拟机实例，有自己的堆
v8::Context 表示 JavaScript 执行上下文，允许全局和内置对象存放在同一个堆中
v8::Local<v8::Value> 句柄提供了 JavaScript 对象在堆中位置的引用（因为垃圾回收等机制可以改变对象在堆中的位置，此处省略其它句柄类型）
v8::HandleScope 句柄作用域，用于自动管理句柄的生命周期
v8::Value 表示 JavaScript 值类型，子类包括 v8::Number、v8::Object 等等
uv_loop_t 表示事件循环。使用 libuv 时两个核心概念是句柄（HandleWrap 子类）和请求（ReqWrap 子类）。
Environment 表示一个 Node.js 实例，包含一个事件循环、v8::Isolate、v8::Realm
Realm Node.js Realm 对象，用于表示 ECMAScript Realm.[[HostDefined]] 字段（不是指语言的 Realm 本身）

启动 Node.js

src/node_main.cc

int main(int argc, char* argv[]) {
  return node::Start(argc, argv);
}

省略非核心代码

src/node.cc

static ExitCode StartInternal(int argc, char** argv) {
  CHECK_GT(argc, 0);
  argv = uv_setup_args(argc, argv);
  std::shared_ptr<InitializationResultImpl> result =
      InitializeOncePerProcessInternal(
          std::vector<std::string>(argv, argv + argc));

  uv_loop_configure(uv_default_loop(), UV_METRICS_IDLE_TIME);
  NodeMainInstance main_instance(snapshot_data,
                                 uv_default_loop(),
                                 per_process::v8_platform.Platform(),
                                 result->args(),
                                 result->exec_args());
  return main_instance.Run();
}

启动 node 主实例

src/node_main_instance.cc

NodeMainInstance::NodeMainInstance(const SnapshotData* snapshot_data,
                                   uv_loop_t* event_loop,
                                   MultiIsolatePlatform* platform,
                                   const std::vector<std::string>& args,
                                   const std::vector<std::string>& exec_args)
    : args_(args),
      exec_args_(exec_args),
      array_buffer_allocator_(ArrayBufferAllocator::Create()),
      isolate_(nullptr),
      platform_(platform),
      isolate_data_(),
      isolate_params_(std::make_unique<Isolate::CreateParams>()),
      snapshot_data_(snapshot_data) {
  isolate_params_->array_buffer_allocator = array_buffer_allocator_.get();
  // 创建 v8 isolate
  isolate_ = NewIsolate(isolate_params_.get(), event_loop, platform, snapshot_data);
}

ExitCode NodeMainInstance::Run() {
  Locker locker(isolate_);
  Isolate::Scope isolate_scope(isolate_);
  HandleScope handle_scope(isolate_);

  ExitCode exit_code = ExitCode::kNoFailure;
  // 创建 Node.js 环境
  DeleteFnPtr<Environment, FreeEnvironment> env = CreateMainEnvironment(&exit_code);

  Context::Scope context_scope(env->context());
  Run(&exit_code, env.get());
  return exit_code;
}

void NodeMainInstance::Run(ExitCode* exit_code, Environment* env) {
  if (*exit_code == ExitCode::kNoFailure) {
    // 运行 Node.js 的本质就是轮转事件循环
    *exit_code = SpinEventLoopInternal(env).FromMaybe(ExitCode::kGenericUserError);
  }
}


DeleteFnPtr<Environment, FreeEnvironment>
NodeMainInstance::CreateMainEnvironment(ExitCode* exit_code) {
  *exit_code = ExitCode::kNoFailure;  // 重置退出码为 0

  HandleScope handle_scope(isolate_);

  Local<Context> context;
  DeleteFnPtr<Environment, FreeEnvironment> env;

  context = NewContext(isolate_);
  CHECK(!context.IsEmpty());
  Context::Scope context_scope(context);
  env.reset(
      // 创建 Node.js 环境
      // 背后是创建 node::Environment 对象
      // 负责管理和维护 JavaScript 代码执行所需的各种资源
      // 例如：V8 隔离/上下文，事件循环、异步操作、主进程状态
      CreateEnvironment(isolate_data_.get(), context, args_, exec_args_));

  return env;
}

CreateEnvironment 函数还会调用启动函数 node::Realm::RunBootstrapping

src/node_realm.cc

MaybeLocal<Value> Realm::RunBootstrapping() {
  EscapableHandleScope scope(isolate_);

  CHECK(!has_run_bootstrapping_code());

  Local<Value> result;
  if (!ExecuteBootstrapper("internal/bootstrap/realm").ToLocal(&result) ||
      !BootstrapRealm().ToLocal(&result)) {
    return MaybeLocal<Value>();
  }

  DoneBootstrapping();

  return scope.Escape(result);
}

可以发现，内部 js 模块通过 node_builtins.cc 来编译运行。
该函数负责通过 realm，传递全局 process primordials internalBinding 等全局对象。
因此，相当于内部模块可以访问额外的 c++ 绑定。

src/node_builtins.cc

MaybeLocal<Value> BuiltinLoader::CompileAndCall(Local<Context> context,
                                                const char* id,
                                                Realm* realm) {
  Isolate* isolate = context->GetIsolate();
  // Detects parameters of the scripts based on module ids.
  // internal/bootstrap/realm: process, getLinkedBinding,
  //                           getInternalBinding, primordials
  if (strcmp(id, "internal/bootstrap/realm") == 0) {
    Local<Value> get_linked_binding;
    Local<Value> get_internal_binding;
    if (!NewFunctionTemplate(isolate, binding::GetLinkedBinding)
             ->GetFunction(context)
             .ToLocal(&get_linked_binding) ||
        !NewFunctionTemplate(isolate, binding::GetInternalBinding)
             ->GetFunction(context)
             .ToLocal(&get_internal_binding)) {
      return MaybeLocal<Value>();
    }
    Local<Value> arguments[] = {realm->process_object(),
                                get_linked_binding,
                                get_internal_binding,
                                realm->primordials()};
    return CompileAndCall(
        context, id, arraysize(arguments), &arguments[0], realm);
  } else if (strncmp(id, "internal/main/", strlen("internal/main/")) == 0 ||
             strncmp(id,
                     "internal/bootstrap/",
                     strlen("internal/bootstrap/")) == 0) {
    // internal/main/*, internal/bootstrap/*: process, require,
    //                                        internalBinding, primordials
    Local<Value> arguments[] = {realm->process_object(),
                                realm->builtin_module_require(),
                                realm->internal_binding_loader(),
                                realm->primordials()};
    return CompileAndCall(
        context, id, arraysize(arguments), &arguments[0], realm);
  }

  // This should be invoked with the other CompileAndCall() methods, as
  // we are unable to generate the arguments.
  // Currently there are two cases:
  // internal/per_context/*: the arguments are generated in
  //                         InitializePrimordials()
  // all the other cases: the arguments are generated in the JS-land loader.
  UNREACHABLE();
}

模块 Bootstrapping

C++ 侧 RunBootstrapping 函数首先执行的是 internal/bootstrap/realm.js 模块。

该文件在 Node.js 创建的每个 realm 中执行，包括主线程、工作线程和 ShadowRealm 的上下文。只有每个 realm 的内部状态和绑定应该在此文件中进行引导，并且不应将全局变量暴露给用户代码。

该文件创建内置模块使用的内部模块和绑定加载器。相比之下，用户态模块使用 lib/internal/modules/cjs/loader.js（CommonJS 模块）或 lib/internal/modules/esm/*（ES 模块）加载。

该文件由 node.cc 编译并在调用 bootstrap/node.js 之前运行，因此加载器在实际启动 Node.js 之前被引导。它创建以下对象：

C++ 绑定加载器：

process.binding()：传统的 C++ 绑定加载器，可以从用户态访问，因为它是一个附加到全局 process 对象的对象。这些 C++ 绑定使用 NODE_BUILTIN_MODULE_CONTEXT_AWARE() 创建，并且其 nm_flags 设置为 NM_F_BUILTIN。
process._linkedBinding()：旨在供嵌入器在其应用程序中添加额外的 C++ 绑定使用。这些 C++ 绑定可以使用带有标志 NM_F_LINKED 的 NODE_BINDING_CONTEXT_AWARE_CPP() 创建。
internalBinding()：私有内部 C++ 绑定加载器，除非通过 require('internal/test/binding')，否则无法从用户态访问。这些 C++ 绑定使用 NODE_BINDING_CONTEXT_AWARE_INTERNAL() 创建，并且其 nm_flags 设置为 NM_F_INTERNAL。

内部 JavaScript 模块加载器：

BuiltinModule：一个最小的模块系统，用于加载位于 lib/**/*.js 和 deps/**/*.js 中的 JavaScript 核心模块。所有核心模块都通过 js2c.cc 生成的 node_javascript.cc 编译到 node 二进制文件中，因此可以更快地加载它们，而无需 I/O 开销。该类默认使 lib/internal/*、deps/internal/* 模块和 internalBinding() 可用于核心模块，并允许核心模块通过 require('internal/bootstrap/realm') 甚至在该文件不是用 CommonJS 风格编写时也可以 require 自身。

其他对象：

process.moduleLoadList：一个数组，记录进程中加载的绑定和模块以及它们的加载顺序。

该文件被编译为好像它被包装在一个函数中，参数由 node::RunBootstrapping() 传递。

`NODE_BINDING_*`

这里举个非常简单的例子

cpp

void ExampleAdd(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  if (args.Length() < 2) {
    isolate->ThrowException(Exception::TypeError(
        String::NewFromUtf8(isolate, "Expected two arguments")));
    return;
  }
  CHECK(args[0]->IsNumber());
  CHECK(args[1]->IsNumber());
  double num1 = args[0]->NumberValue(isolate->GetCurrentContext()).FromMaybe(0.0);
  double num2 = args[1]->NumberValue(isolate->GetCurrentContext()).FromMaybe(0.0);
  double sum = num1 + num2;
  args.GetReturnValue().Set(Number::New(isolate, sum));
}

void Initialize(Local<Object> target,
                Local<Value> unused,
                Local<Context> context,
                void* priv) {
  Environment* env = Environment::GetCurrent(context);
  SetMethod(context, target, "exampleAdd", ExampleAdd);
}

// Run the `Initialize` function when loading this binding through
// `internalBinding('cares_wrap')` in Node.js's built-in JavaScript code:
NODE_BINDING_CONTEXT_AWARE_INTERNAL(cares_wrap, Initialize)

使用 NODE_BINDING_CONTEXT_AWARE_INTERNAL 注册用于 internalBinding() 查找

src/node_binding.cc

void GetInternalBinding(const FunctionCallbackInfo<Value>& args) {
  Realm* realm = Realm::GetCurrent(args);
  Isolate* isolate = realm->isolate();
  HandleScope scope(isolate);

  CHECK(args[0]->IsString());

  Local<String> module = args[0].As<String>();
  node::Utf8Value module_v(isolate, module);
  Local<Object> exports;

  node_module* mod = FindModule(modlist_internal, *module_v, NM_F_INTERNAL);
  if (mod != nullptr) {
    exports = InitInternalBinding(realm, mod);
    realm->internal_bindings.insert(mod);
  } else {
    return THROW_ERR_INVALID_MODULE(isolate, "No such binding: %s", *module_v);
  }

  args.GetReturnValue().Set(exports);
}

观察 NODE_BINDING_* 宏可以发现，这个宏为当前的 C++ 文件导出 static node::node_module _module 变量。
定义的内部绑定可以通过 node::Environment 的上下文进行加载。

←Back to home

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