js模块机制

February 28, 2025

假设读者已熟悉 esm/cjs 语义，若不了解，参考：

服务器环境只以 Node.js 为例。

本文不涉及具体运行时实现，仅考虑标准。关于 Node.js 的模块实现，见Node.js模块处理机制。

对于 bundler 部分，只以 webpack（对于 cjs→cjs）和 rollup（对于 esm→esm）为例，这是它们优先支持的模块系统。

ES Module

概况性地说，es 模块流程如下：

构建（construction）：解析（resolution），获取（fetch），语法解析（Parse）
实例化（instantiation）
执行（evaluation）

其中，宿主负责语法解析前的操作，引擎负责之后的工作。

esm 的特点是静态模块发现（生成模块依赖图）可以在语法解析时完成（而无需在执行时）。
若处理动态导入，只需再创建一个单独的模块依赖图即可（这一点非常重要）。

cjs 是为本地文件系统设计的模块系统，而 esm 则需要单独考虑模块获取流程。

esm 通过语言规范引入了新的语义，该语义为静态分析（即语法解析）暴露出模块系统。
这种静态特性不仅优化了请求瀑布（实现并发加载），对构建系统也很有帮助。

不要误解解释器和ES代码的同步或异步执行。对于ES代码，简单来说，只有立即推入执行上下文堆栈执行才是同步。
而解释器的异步流程很可能根本无法在ES代码中观测到，换言之，解释器的异步流程对ES脚本来说可以是同步。对并发问题也是如此。

规范

timeline：

ES2015 支持模块
ES2020 支持 import() export * as ns from 'module' import.meta
ES2022 支持 top-level await

有一些异步执行的提案还在推进中，如defer-import-eval

模块记录

Module Record

字段名称	值类型	含义
`[[Realm]]`	一个 Realm Record	创建此模块的 Realm。
`[[Environment]]`	一个 Module Environment Record 或 empty	包含此模块的顶层绑定的 Environment Record。此字段在模块链接时设置。
`[[Namespace]]`	一个 Object 或 empty	如果已为此模块创建模块命名空间对象（28.3），则为该对象。
`[[HostDefined]]`	任何类型（默认值为 undefined）	保留字段，供需要将附加信息与模块关联的宿主环境使用。

Cyclic Module Records

字段名称	值类型	含义
`[[Status]]`	new, unlinked, linking, linked, evaluating, evaluating-async, 或 evaluated	初始状态为 new。随着模块在其生命周期中的进展，依次转换为 unlinked, linking, linked, evaluating，可能为 evaluating-async，以及 evaluated。 evaluating-async 表示此模块已排队等待其异步依赖项完成后执行，或者它是一个 `[[HasTLA]]` 字段为 true 的模块，该模块已执行并正在等待顶层完成。
`[[EvaluationError]]`	一个 throw completion 或 empty	一个 throw completion，表示求值期间发生的异常。如果未发生异常或 `[[Status]]` 不是 evaluated，则为 undefined。
`[[DFSIndex]]`	一个 integer 或 empty	仅在 Link 和 Evaluate 期间使用的辅助字段。如果 `[[Status]]` 是 linking 或 evaluating，则此非负数记录了在深度优先遍历依赖关系图期间首次访问该模块的点。
`[[DFSAncestorIndex]]`	一个 integer 或 empty	仅在 Link 和 Evaluate 期间使用的辅助字段。如果 `[[Status]]` 是 linking 或 evaluating，则这要么是模块自身的 `[[DFSIndex]]`，要么是同一强连通分量中“更早”模块的 `[[DFSIndex]]`。
`[[RequestedModules]]`	一个由字符串组成的 List	一个 List，包含此记录所代表的模块用于请求导入模块的所有 ModuleSpecifier 字符串。List 按照源代码文本出现的顺序排列。
`[[LoadedModules]]`	一个由 Records 组成的 List，其中包含字段 `[[Specifier]]` (一个字符串) 和 `[[Module]]` (一个 Module Record)	一个从该记录所代表的模块用于请求导入模块的 specifier 字符串到已解析的 Module Record 的映射。该列表不包含两个具有相同 `[[Specifier]]` 的不同 Records。
`[[CycleRoot]]`	一个 Cyclic Module Record 或 empty	循环中第一个被访问的模块，即强连通分量的根 DFS 祖先。对于不在循环中的模块，这将是模块本身。一旦 Evaluate 完成，模块的 `[[DFSAncestorIndex]]` 就是其 `[[CycleRoot]]` 的 `[[DFSIndex]]`。
`[[HasTLA]]`	一个 Boolean	此模块是否是单独异步的（例如，如果它是一个包含顶层 await 的 Source Text Module Record）。具有异步依赖项并不意味着此字段为 true。此字段在模块解析后不得更改。
`[[AsyncEvaluation]]`	一个 Boolean	此模块本身是否是异步的，或者是否具有异步依赖项。注意：设置此字段的顺序用于对排队的执行进行排序，请参见 16.2.1.5.3.4。
`[[TopLevelCapability]]`	一个 PromiseCapability Record 或 empty	如果此模块是某个循环的 `[[CycleRoot]]`，并且已对该循环中的某个模块调用了 Evaluate()，则此字段包含该整个求值的 PromiseCapability Record。它用于解决从 Evaluate() 抽象方法返回的 Promise 对象。对于该模块的任何依赖项，此字段将为空，除非已为其中一些依赖项启动了顶层 Evaluate()。
`[[AsyncParentModules]]`	一个由 Cyclic Module Records 组成的 List	如果此模块或依赖项的 `[[HasTLA]]` 为 true，并且执行正在进行中，则这会跟踪此模块的顶层执行作业的父导入器。这些父模块不会在此模块成功完成执行之前开始执行。
`[[PendingAsyncDependencies]]`	一个 integer 或 empty	如果此模块有任何异步依赖项，则这会跟踪此模块剩余要执行的异步依赖模块的数量。当此字段达到 0 并且没有执行错误时，将执行具有异步依赖项的模块。

模块命名空间

动态导入有单独的运行时表示，这正确的保证了命名空间是密封、可枚举的。

内部插槽	类型	描述
`[[Module]]`	一个 Module Record	此命名空间公开其导出的 Module Record。
`[[Exports]]`	一个由字符串组成的 List	一个 List，其元素是作为此对象自身属性公开的导出名称的字符串值。该列表按照词典编码单元顺序排序。

模块处理流程

这里以 HTML标准和 ECMA262 加以说明，浏览器环境：

https://html.spec.whatwg.org/multipage/webappapis.html#scripting-processing-model

https://tc39.es/ecma262/multipage/ecmascript-language-scripts-and-modules.html#sec-example-cyclic-module-record-graphs

根据规范，只考虑静态导入导出，简单来说：

递归地加载模块，构建模块依赖图（注意：由浏览器网络请求模块，一旦失败，例如跨源错误和模块解析失败，整个过程将终止）
递归地连接模块，检查导入导出的标识符是否正确，对每个模块 InitializeEnvironment（一旦失败，例如导入了不存在的标识符，整个过程将终止）
按照依赖图执行所有模块（只有这个步骤有副作用，因此不允许重复执行）

Bundler

对于浏览器来说，bundler 还是很有必要的。使用 <link rel="modulepreload">虽然可以优化请求瀑布问题，还是 bundler 来实现移除死代码和代码压缩。

以 rollup 为例，rollup 自身实现了语法解析器，AST 格式遵循 estree 规范。

https://stackblitz.com/edit/rollup-bundle-demo-ed8ygxp9?file=src%2Findex.js

bundler 的特点在于它不需要执行模块，但需要合并和生成模块。
因此，显然也需要记录模块依赖图、检查导入导出的标识符。无需执行。
bundler 也需要考虑解释器无需处理的问题，例如，如何生成模块文件，如何处理多入口模块。

下面我们考虑实现一个简单的 esm bundler，给定（可以是多个）入口文件，首先递归解析出所有模块。模块表示如下：

interface Module {
    /** 文件系统绝对路径 */
    path: string;
    /** AST */
    ast: any;
    /** 表示是否是入口文件，入口文件必须生成对应输出模块 */
    isEntry: boolean;
}

首先考虑最简单的情况：

import "./entry.js";
import entry from "./entry.js";
import * as a from "./entry.js";
import { a, b } from "./entry.js";

由于 entry.js 是入口文件，打包后也存在 entry.js，因此 import 语句可以保留。这种情况下无需处理。

若不是入口文件，假设 not_entry.js 只被此模块引入，则 not_entry.js 不存在对应的输出模块。

import "./not_entry.js";
import { a, b } from "./not_entry.js";
import * as a from "./not_entry.js";
import not_entry from "./not_entry.js";

考虑 not_entry.js 中的 export 语句如下：

not_entry.js

const str = "not_entry.js";
console.log(str);
export { str };
export default str;

若不考虑支持 tree-shaking，可以将 import 改写为：

const bundled$not_entry = ((exports = {}) => {
    const str = "not_entry.js";
    console.log(str);
    exports.str = str;
    exports.default = str;
    return exports;
})();

const { a, b } = bundled$not_entry;
const a = bundled$not_entry;
const { default: not_entry } = bundled$not_entry;

not_entry.js 模块中也可以包含 import，若导入的是入口文件，直接将 import 提升即可，否则可以递归处理。

这种方式相当于 webpack 模块中心实现，可以实现模块只执行一次的预期效果。
然而，这种改写方法有局限性：无法实现 esm 的 live-binding 效果，因为导出变成了赋值行为，而非预期的绑定行为。

要实现 tree-shaking，语法解析时，需要确定何处使用了导入的变量，然后改写变量名称即可。
对于未使用的标识符（未被导入，且不被模块副作用引用），其声明和赋值语句都可以直接删除。

假设 not_entry.js 被多个入口模块引入，则必须为该模块生成单独的 chunk 模块，而不能采取替换方法。
因为需要保证导入方导入的是同一个模块。

综上可以发现，这些 chunk 生成的模式最终都可以通过一种有向图算法来描述。

esm 中，同一个模块标识符的模块只运行一次。由于模块可以有副作用，因此 Bundler 需要考虑模块执行顺序。
bundler 相比于实际执行，只是少了实例化和执行阶段，因此它也是从入口模块出发，深度优先。
bundler 也是保守的，因为需要最大程度保证产物与输入的执行结果一致（特别是实际执行顺序）。
由于语法限制加上 bundler语义本身的局限，并非所有输入情况都可以编译出运行结果一致的产物。

循环依赖

esm bundler 天生可以处理循环依赖，因为同标识符模块仅执行一次。
由于仅执行一次，非入口模块被替换时，代码顺序自然在更上方，这同时满足了执行顺序和声明作用域问题。

不过存在一些模块输入情况，解释器会报错，然而此时 bundler 根本无法完成代码生成：

a.js

import { a } from "./a.js"; // SyntaxError: Detected cycle while resolving name 'a' in './a.js'
export { a };

a.js

import { a } from "./a.js";
const aPlusOne = a + 1; // ReferenceError: Cannot access 'a' before initialization
export { aPlusOne as a };

静态 import 语句必须为顶部声明

此语法限制 + 外部依赖可能出现问题，例如：

// main.js
import "./polyfill.js";
import "external";
console.log("main");

// polyfill.js
console.log("polyfill");

esm 执行是先构建模块依赖图，然后按依赖图执行。
换言之，是语法解析->确定依赖关系->按依赖顺序执行。而非等遇见 import 语句再执行。

这相当于，import 语句会提升到顶部！

注意：这与 var/函数声明提升原理完全不同，因为 import/export 模块依赖图解析发生在代码执行之前，然后按图顺序执行，只是表现上看起来像是提升了。

// output.js
console.log("polyfill");
import "external"; // 由于 import 语句会提升到顶部，因此 polyfill 在 external 模块后执行
console.log("main");

导入映射

html

<script type="importmap">
    {
        "imports": {
            "square": "./module/shapes/square.js",
            "shapes/": "./module/shapes/",
            "modules/shapes/": "./module/src/shapes/",
            "modules/square": "./module/src/other/shapes/square.js",
            "https://example.com/modules/square.js": "./module/src/other/shapes/square.js",
            "../modules/shapes/": "/modules/shapes/"
        },
        "scopes": {
            "/modules/customshapes/": {
                "square": "https://example.com/modules/shapes/square.js"
            }
        }
    }
</script>

CommonJS

cjs 是在无需 ecma262 改动下支持的，换言之，它没有改变语言本身的任何语义。这也意味着运行时本身必须对其做一些支持。

Runtime

cjs 导出单个值，而 esm 导出一个不可变命名空间，其中包含一组绑定（因此需要语义支持）。
由于 esm 导入不可变绑定，其对循环依赖的处理是很自然的。

cjs 对循环依赖的处理简单粗暴，但由于只支持导出单个值，导入/导出方必须对共享值做特殊支持。

//------ a.js ------
console.log('a: before require("./b")');
const b = require("./b");
console.log('a: after require("./b")');

function foo() {
    b.bar();
}

module.exports.foo = foo;
console.log("a: end");

//------ b.js ------
console.log('b: before require("./a")');
const a = require("./a");
console.log('b: after require("./a")');

function bar() {
    if (Math.random()) {
        a.foo();
    }
}

module.exports.bar = bar;
console.log("b: end");

若先执行 a.js，实际流程是：

a: before require("./b")
    b: before require("./a")
    b: after require("./a")
    b: end
a: after require("./b")
a: end

因此 cjs 模块导入时，导出方可能还未完成导出过程（还没运行完）。
这也是为什么在循环导入时有必要导入（引用）整个导出值。

简单来说：cjs 模块导出默认是空对象（这很重要，这里我们称为早期绑定），require 导入的值是导出方当前导出值的拷贝。

Bundler

webpack 源码：https://github.com/webpack/webpack/blob/main/lib/javascript/JavascriptModulesPlugin.js

例子：https://stackblitz.com/edit/webpack-bundle-demo?file=src%2Findex.js

//prettier-ignore
/******/ (() => { // webpackBootstrap
/******/ 	var __webpack_modules__ = ({

/***/ "./src/a.js":
/*!******************!*\
  !*** ./src/a.js ***!
  \******************/
/***/ ((module, __unused_webpack_exports, __webpack_require__) => {

console.log('a: before require("./b")');
const b = __webpack_require__(/*! ./b */ "./src/b.js");
console.log('a: after require("./b")');

function foo() {
    b.bar();
}

module.exports.foo = foo;
console.log("a: end");

/***/ }),

/***/ "./src/b.js":
/*!******************!*\
  !*** ./src/b.js ***!
  \******************/
/***/ ((module, __unused_webpack_exports, __webpack_require__) => {

console.log('b: before require("./a")');
const a = __webpack_require__(/*! ./a */ "./src/a.js");
console.log('b: after require("./a")');

function bar() {
  if (!Math.random()) {
    a.foo();
  }
}

module.exports.bar = bar;
console.log('b: end');


/***/ }),

/***/ "./src/index.js":
/*!**********************!*\
  !*** ./src/index.js ***!
  \**********************/
/***/ ((module, __unused_webpack_exports, __webpack_require__) => {

module.exports.index = function () {
  (__webpack_require__(/*! ./a */ "./src/a.js").foo)();
};


/***/ })

/******/ 	});
/************************************************************************/
/******/ 	// The module cache
/******/ 	var __webpack_module_cache__ = {};
/******/ 	
/******/ 	// The require function
/******/ 	function __webpack_require__(moduleId) {
/******/ 		// Check if module is in cache
/******/ 		var cachedModule = __webpack_module_cache__[moduleId];
/******/ 		if (cachedModule !== undefined) {
/******/ 			return cachedModule.exports;
/******/ 		}
/******/ 		// Create a new module (and put it into the cache)
/******/ 		var module = __webpack_module_cache__[moduleId] = {
/******/ 			// no module.id needed
/******/ 			// no module.loaded needed
/******/ 			exports: {}
/******/ 		};
/******/ 	
/******/ 		// Execute the module function
/******/ 		__webpack_modules__[moduleId](module, module.exports, __webpack_require__);
/******/ 	
/******/ 		// Return the exports of the module
/******/ 		return module.exports;
/******/ 	}
/******/ 	
/************************************************************************/
/******/ 	
/******/ 	// startup
/******/ 	// Load entry module and return exports
/******/ 	// This entry module used 'module' so it can't be inlined
/******/ 	var __webpack_exports__ = __webpack_require__("./src/index.js");
/******/ 	var __webpack_export_target__ = exports;
/******/ 	for(var __webpack_i__ in __webpack_exports__) __webpack_export_target__[__webpack_i__] = __webpack_exports__[__webpack_i__];
/******/ 	if(__webpack_exports__.__esModule) Object.defineProperty(__webpack_export_target__, "__esModule", { value: true });
/******/ 	
/******/ })()
;

原理很简单，模拟 node 运行时逻辑。

__webpack_modules__: 一个对象，包含了所有模块定义。键为模块 ID，值为模块包装函数
__webpack_module_cache__: 一个对象，作为模块缓存。键为模块 ID，值是已加载的模块对象
__webpack_require__: 模块加载器函数。负责加载、缓存和执行模块
启动代码: 加载入口模块，并将入口模块的导出赋值给全局 exports 对象

function __webpack_require__(moduleId) {
    // 检查模块是否在缓存中
    var cachedModule = __webpack_module_cache__[moduleId];
    if (cachedModule !== undefined) {
        // 若已缓存，则直接返回
        return cachedModule.exports;
    }
    // 执行模块并放入缓存
    var module = (__webpack_module_cache__[moduleId] = {
        exports: {},
    });

    // 此处执行
    __webpack_modules__[moduleId](module, module.exports, __webpack_require__);

    // 返回模块导出
    return module.exports;
}

Bundler 高级部分

Tree Shaking / Dead Code

优化产物体积就在于消除一些保守的部分（如副作用）。

显然，esm 天生适合 tree-shaking，因为导出和（静态）导入只能发生在顶级作用域，因此所有导入导出的标识符都是确定的，并且不能动态修改。

rollup 以 tree-shaking 而闻名，在 webpack 中支持 tree-shaking 也需要保证输入是 es 模块。
并且支持一些约定，以进行优化。

注意，cjs 只导出单个值（esm 为多值），可在任意时刻修改导出（esm 仅允许静态导出），并在导入时是复制行为（esm 为绑定行为）。
理论上说，cjs 也能够一定程度支持 tree-shaking，因为导入行为可以看作是静态的。

Lazy Loading / 多入口

由于 esm 支持动态导入，lazy loading 就非常简单了。对于 bundler，将被动态导入的模块也视为入口模块即可。

另一种场景则是为 bundler 手动配置分块，处理方式也是类似的。

https://web.developers.google.cn/articles/use-long-term-caching?hl=zh-cn#lazy-loading

Hot Module Replacement

热模块替换比热重载的优点就是能够保留应用的状态，这需要应用本身做支持，bundler 只是通知应用程序模块发生了变更。

显然，HMR 并非 bundler 的本职工作，而是开发服务器实现的。

理论上来说可以很简单，开发服务器和浏览器建立单向连接（SSE/WS都可以实现），开发服务器记录依赖状态并在依赖变更时发送通知即可。
开发服务器还需要为框架做支持，例如如果是 react 组件，为保留组件状态，可以创建代理组件保证实际的组件，状态提升到代理组件上，从而避免状态丢失。

转换

esm 到 cjs

export var foo = 1;

export function bar() {
    return foo++;
}

export default function baz() {
    return bar();
}

注意到 __esModule，这标记 esm 使用了默认导出。

"use strict";

Object.defineProperty(exports, "__esModule", { value: true });

exports.foo = 1;

function bar() {
    return exports.foo++;
}

function baz() {
    return bar();
}

exports.bar = bar;
exports.default = baz;

导入的转换也可以很简单

import foo from "./foo"; // 假设 foo 是 esm 编译出的 cjs 模块
// ↓↓↓↓
const { default: foo } = require("./foo");

import * as foo from "./foo";
// ↓↓↓↓
const foo = require("./foo");

import { bar, baz } from "./foo";
//↓↓↓↓
const { bar, baz } = require("./foo");

function func(name) {
    const foo = import(`./${name}`);
    //↓↓↓↓
    const foo = Promise.resolve(require(`./${name}`));
}

cjs 到 esm

强烈建议阅读 @rollup/plugin-commonjs 文档。文档中讨论了 rollup 的 cjs 转换 esm 实现。
该插件能够配置处理各种依赖情况，包括循环依赖和混合依赖。

下面我们以 vite Pre-Bundling 为例，它是一种简单但有效的方法。做如下转换：

// add.js
exports.add = (a, b) => a + b;

// minus.js
exports.minus = (a, b) => a - b;

// math.js
exports.calc = (a, b, operate) => {
    const calc =
        operate === "+" // condition require
            ? require("./add").add(a, b)
            : require("./minus").minus(a, b);
    return calc(a, b);
};

转换为

var __commonJS = (cb, module = { exports: {} }) =>
    function __require2() {
        const cjs_wrapper = Object.values(cb)[0]; // wrapper function
        cjs_wrapper(module.exports, module); // inject exports, module
        return module.exports;
    };

// add.js
var require_add = __commonJS({
    "add.js"(exports, module) {
        exports.add = (a, b) => a + b;
    },
});

// minus.js
var require_minus = __commonJS({
    "minus.js"(exports, module) {
        exports.minus = (a, b) => a - b;
    },
});

// math.js
var require_math = __commonJS({
    "math.js"(exports, module) {
        exports.calc = (a, b, operate) => {
            const calc =
                operate === "+" // condition require
                    ? require_add().add(a, b)
                    : require_minus().minus(a, b);
            return calc(a, b);
        };
    },
});

export default require_math(); // -> { calc: Function }

这样即可利用 cjs 唯一导出的特性。可以看出，打包后的 esm 也导出单值（默认导出）。

const math = require("./math");
//↓↓↓↓
import math from "./math";

const { calc } = require("./math");
//↓↓↓↓
import math from "./math";
const { calc } = math;

cjs 本身可能是 esm 的编译结果，此时 __esModule 就起作用了。

// mod.cjs
exports.default = 3;
// mod-compiled.cjs
exports.__esModule = true;
exports.default = 3;

// main1.mjs
import foo from "./mod.cjs";
import bar from "./mod-compiled.cjs";
console.log(foo); // -> { default: 3 }
console.log(bar); // -> 3

// main2.mjs
import * as foo from "./mod.cjs";
import * as bar from "./mod-compiled.cjs";
console.log(foo); // -> { default: 3 }
console.log(bar); // -> { default: 3, __esModule: true }

←Back to home

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