先做一件会让人愣一下的小事。建两个文件,一个导出计数器,一个导入它并调用:
// counter.js
export let count = 0;
export function increment() {
count += 1;
}
// main.js
import { count, increment } from "./counter.js";
console.log("调用前", count);
increment();
console.log("调用后", count);
如果你是从 CommonJS 或者「解构赋值」的世界里过来的,大概会预期两次都打印 0:import 看起来就是把一个值拿到了本地,之后别人怎么改,跟我手里的这份没关系。但浏览器里实际打印的是 0 和 1。你手里的 count 跟着 counter.js 里那个变量一起变了。
不是打包工具做了什么魔法,这里也完全没用构建工具。type="module" 的原生脚本就是这个行为。第一次撞见会怀疑自己看错了,顺手写一行 count = 99 想改回去,控制台给的是 TypeError:能读不能写。
这篇就从这个现象往下挖:ESM 到底在什么时候加载、什么时候执行,import 拿到的到底是什么东西,为什么两个文件互相引用时有时能用、有时直接报错。这些不是规范里的边角料,它们决定了你项目里的模块初始化顺序、SSR 里的状态污染,以及打包之后的调试难度。
先把这个现象复现出来
上面那段代码不能直接双击 HTML 打开,浏览器会拦。模块脚本按 CORS 规则抓取,file:// 打开时源是不透明的,控制台会给你一句跨域错误。起一个本地静态服务最省事:
python -m http.server 8000
# 然后访问 http://localhost:8000/index.html
页面里这样引:
<script type="module" src="./main.js"></script>
打开控制台,你会看到 0 和 1。再在 main.js 里加一行 count = 99,刷新,报错。到这里现象就稳定了:导入的是「一个会变、但不能改」的东西。
三个猜测,一个个排掉
遇到这种反直觉的行为,先别急着背结论。列出几种可能的解释,再用最小的实验去排除,这个过程比记住答案有用。
猜测一:变量被提升成了全局变量。 如果 count 挂在 window 上,两边看到同一个值也说得通。验证很简单:在 main.js 里打印 window.count,是 undefined。再看 counter.js 里 count 也不是全局属性。排除。
猜测二:打包器或者编译器把它改写成了 getter。 这个方向最接近真相,但这里没有打包器。把文件直接用原生 ESM 跑,行为一样。说明这是语言和宿主环境层面的机制,不是工具链的产物。
猜测三:两个模块共享同一个作用域。 如果是共享作用域,counter.js 里的局部变量应该能从 main.js 直接访问。实际上不行,main.js 里除了导入的那几个名字,别的一个都看不见。模块仍然是各自独立的作用域。
排除完剩下的解释是:两个模块各自有自己的变量,但它们之间的连接不是「复制一份值」,而是「一条指向对方变量的引用」。规范里管这个叫间接绑定(indirect binding)。名字听着绕,意思很朴素:main.js 里的 count 不是一个装数字的盒子,而是一根线,另一头拴在 counter.js 的 count 盒子上。盒子里的数字换了,你顺着线看过去,看到的自然是新数字。
浏览器拿到模块之后,其实分三步
要理解「线」是什么时候接上的,得看模块的加载过程。大部分人脑子里的模型是「下载完就执行」,实际要细得多。规范把这件事拆成三个阶段,前两个阶段都不执行任何一行代码。
为什么非要拆成这样?因为静态的 import 让浏览器在执行之前就能看到整张依赖图。它可以在代码还没跑的时候就发现「这个模块引用了不存在的导出」,也可以在两个模块互相引用时,先把两边都准备好再决定执行顺序。如果边下载边执行,循环依赖根本没法处理。
第一步里有个容易忽略的细节:import 只能写在模块顶层,不能塞进 if 或者函数里。这不是风格约束,语法上直接不允许:
if (needChart) {
import { draw } from "./chart.js"; // SyntaxError
}
原因还是那一条:依赖图要在执行前画出来。条件加载要用动态的 import(),它返回 Promise,属于下一节的内容。
实例化:接的不是值,是绑定
依赖图建好之后,每个模块会拿到一个模块环境记录,你可以理解成一个作用域对象,里面按名字放着这个模块所有导出和内部的顶层变量。然后是实例化:对于每一条 import { count } from "./counter.js",引擎不会去读 counter.js 里 count 当前的值,而是在当前模块的环境里建一个间接绑定,指向 counter.js 环境里那个叫 count 的槽位。
这一步结束之后,所有模块的导出都已经「接好线」了,但所有代码一行都没跑。这就是循环依赖能工作的前提:A 引 B、B 引 A,两边先把线接上,再去讨论谁先执行。
ESM:活的绑定
import 得到的是指向导出方变量的引用。导出方改了值,导入方下一次读取就能看到。导入方不能赋值,因为绑定是只读的。
CommonJS:值的拷贝
require 返回 module.exports 那个对象。解构出来的数字、字符串就是当时的一份拷贝,之后对方改了自己那份,你手里这份不会动。
CommonJS 的行为用三行代码就能看出来:
// counter.cjs
let count = 0;
module.exports = { count, increment() { count += 1; } };
// main.cjs
const { count, increment } = require("./counter.cjs");
console.log(count); // 0
increment();
console.log(count); // 0,还是 0
console.log(require("./counter.cjs").count); // 1
同样是「导入」,两种模块系统的语义完全不同。这不只是历史包袱的问题,它直接影响你迁移时的判断:一段依赖「导出方改了值、导入方能看到」的代码,从 CJS 换成 ESM 之后行为会变。
还有一个容易踩的细节:函数声明是在实例化阶段就初始化好的,而 const、let 要等到求值阶段执行到那一行才有值。这解释了为什么很多循环依赖的项目「平时没事」:只要互相引用的是函数,实例化时函数就已经可用;一旦引用了 const 定义的常量或对象,就可能在求值阶段出事。
求值:深度优先,后序,只跑一次
第三步才是真正执行模块体。规则可以概括成三句话:先求值依赖,再求值自己;同一层的依赖按 import 语句出现的顺序来;每个模块只求值一次。
// a.js
import "./b.js";
console.log("a 执行");
// b.js
console.log("b 执行");
// main.js
import "./a.js";
console.log("main 执行");
控制台顺序是 b、a、main。这就是「后序」:把 a 当作树上的一个节点,先把它下面的子树处理完,再处理它自己。
循环依赖的经典表现也来自这套规则。下面这对模块,跑起来会在 b.js 里直接抛错:
// a.js
import { b } from "./b.js";
export const a = "A";
console.log("a 里看到 b =", b);
// b.js
import { a } from "./a.js";
export const b = "B";
console.log("b 里看到 a =", a);
求值从 a 开始,先去求值它的依赖 b;b 的依赖 a 正在求值中,跳过;于是 b 的模块体开始执行,执行到 console.log 时读 a。此时 a 的 const 还没执行到赋值那一行,绑定存在但没初始化,读它触发暂时性死区,报:
ReferenceError: Cannot access 'a' before initialization
把 export const a = "A" 改成 export var a = "A",行为立刻变成打印 undefined。因为 var 在实例化阶段就被初始化为 undefined,不属于死区。改成 export function a() {},连 undefined 都不会出现,函数在实例化时就可用。
这三种写法的差别不是「哪个更安全」,而是同一个机制在不同声明形式下的表现。看懂这一点,下次遇到循环依赖报错,你就知道该看的是「谁在求值时读了对方还没初始化的绑定」,而不是去调整 import 的书写顺序。
运行时剩下的几样东西
动态导入。 import() 不是语句,是一个返回 Promise 的表达式,可以写在任何地方:
button.addEventListener("click", async () => {
const { drawChart } = await import("./chart.js");
drawChart(data);
});
它在调用时才去抓取模块,抓取和求值走的是同一套模块记录,同一个 URL 只会有一份实例。所以动态导入两次同一个文件,拿到的是同一份导出,不会重新执行。区别在于时机:静态导入在首屏加载链路里,动态导入把这段成本推迟到用户真的需要时。
import.meta。 模块里可以读到当前模块的元信息,最常用的是 import.meta.url,也就是这个模块被解析后的绝对地址。拼资源路径时用它,比用相对路径更不容易出错。Node 里还有 import.meta.dirname 之类的扩展,浏览器里没有,写同构代码时要判断环境,或者干脆改用构建工具注入的常量。
顶层 await。 模块顶层可以直接写 await。这会让这个模块的求值变成异步的,依赖它的模块必须等它完成。注意范围:它不是把整个页面卡住,只影响依赖链上的模块。但如果这个模块在首屏的关键路径上,用户看到的就是一段额外的白屏。
// config.js
const res = await fetch("/api/config");
export const config = await res.json();
// app.js
import { config } from "./config.js"; // 会等到 config.js 里两个 await 完成
副作用导入。 import "./polyfill.js" 不取任何导出,只为执行那个模块。它是最容易被忽略的依赖:删除时以为没人用,实际上有模块靠它在启动时注册全局东西。
打包器做的事,其实是伪造这套系统
生产环境很少让浏览器直接跑几十上百个原生模块。打包器会把整张图折成几个文件,然后在产物里自己实现一套模块加载。以 webpack 为例,产物长这样:
var __webpack_modules__ = {
"./src/counter.js": function (module, exports, __webpack_require__) {
let count = 0;
function increment() { count += 1; }
Object.defineProperty(exports, "count", {
enumerable: true,
get: function () { return count; }
});
exports.increment = increment;
}
};
var __webpack_module_cache__ = {};
function __webpack_require__(id) {
if (__webpack_module_cache__[id]) return __webpack_module_cache__[id].exports;
var module = __webpack_module_cache__[id] = { exports: {} };
__webpack_modules__[id](module, module.exports, __webpack_require__);
return module.exports;
}
模块被包成函数,依赖关系变成函数参数,缓存变成一个普通对象,导出用 get 定义,这样才保住了「活的绑定」这个语义。流程和原生 ESM 神似,但顺序、时机、错误处理都不完全一样:原生 ESM 是先接好所有线再执行,webpack 的运行时是按 require 的调用顺序递归执行,遇到循环依赖时拿到的是「执行了一半的 exports 对象」。
Rollup 和 esbuild 走的另一条路,叫作用域提升:能合并的模块直接摊平到同一个作用域,导入导出变成同一个变量的引用,产物里甚至看不到模块包装函数。它更快、更小,但对循环依赖和副作用边界的处理更保守,遇到不确定的情况就退回逐个包装。
这就是为什么线上 bug 常常「本地复现不了」:你调试的模块执行顺序,和源码里的 import 顺序已经不是一回事了。下一篇文章会把这条折叠链路拆开讲。
现象、机制、怎么自己验证
把这一篇里出现的现象集中列一下。右边那列是验证手段,建议真的动手做一遍,比读三遍结论管用。
| 现象 | 真实机制 | 怎么验证 |
|---|---|---|
| 导出方修改变量,导入方读到的是新值 | 导入是间接绑定,指向导出方的绑定槽,不是值拷贝 | 在导入方调用导出方的修改函数,前后各打印一次;再试着给导入名赋值,会抛 TypeError |
循环依赖时报 Cannot access 'a' before initialization |
const/let 在求值前处于暂时性死区 |
把同一个例子里的 const 换成 var,报错变成 undefined;再换成函数声明,正常输出 |
| 两个入口都导入同一模块,日志只出现一次 | 模块记录带求值状态,成功后不再执行;失败也会缓存错误 | 两个模块各打印一行带时间戳的日志,比较两次输出;再故意抛错,看第二次导入是否重新执行 |
把 import 写进 if 直接语法报错 |
静态导入必须在顶层,依赖图要在执行前确定 | 在控制台贴一段带条件 import 的模块代码,观察 SyntaxError;改用 import() 后正常 |
双击 HTML 用 file:// 打开,模块加载失败 |
模块脚本按 CORS 规则抓取,file:// 的源被视为不透明 |
用本地静态服务打开同一份文件,Network 里能看到每个模块的请求和状态码 |
| 打包后循环依赖的表现和原生不一样 | 打包器用自己的 require 与缓存,递归执行顺序由运行时决定 |
对比产物里的模块包装函数与源码,或关掉打包直接用原生 ESM 跑同一个例子 |
| 改一个「没人用」的模块,样式或行为却变了 | 副作用导入:该模块顶层有注册、打补丁之类的代码 | 在模块顶层加一行日志,看它有没有被打印;再全局搜索这个路径被谁引用 |
边界与代价
原生 ESM 的请求瀑布。 浏览器要先拿到入口,解析出 import,才知道下一层要下什么。依赖链越深,串行等待越多。HTTP/2 的多路复用能减少连接开销,但减少不了「先知道再请求」这个顺序。<link rel="modulepreload"> 可以让关键模块提前抓取,代价是你得自己维护这份清单,漏一个就白搭。
顶层副作用是最贵的隐形成本。 一个模块在顶层发请求、读 localStorage、注册全局变量,导入它就等于执行这些动作。这在浏览器里只是慢一点,在 SSR 里会变成事故:模块在服务端进程里只求值一次,状态却被所有请求共享。用户 A 的登录信息泄漏给用户 B,本地单请求测试完全看不出来。请求级状态必须放在函数参数、请求对象或者框架提供的上下文里,不能放模块顶层。
顶层 await 会把关键路径拉长。 它只阻塞依赖它的模块,这一点常被误解成「不会影响首屏」。实际上如果一个入口依赖了带顶层 await 的配置模块,整棵树都得等那个请求回来。能挪到运行时再取的配置,就别放模块顶层。
活的绑定让跨模块可变状态更难发现。 一个导出 let currentUser 的模块,看起来只是导出了一个变量,实际上它是个全局状态,任何导入它的模块都能读到最新值。这种写法在小项目里方便,在大项目里会让「这个值什么时候被改的」变得难以追踪。真要共享状态,用明确的状态容器,别靠模块变量的副作用。
双格式发布的坑。 一个库同时提供 CJS 和 ESM 入口,打包器可能在不同路径下各引入一份,导致两份单例:你在这边设置的全局配置,那边看不到。这是 dual package hazard,排查时表现为「同一个库的行为不一致」。选库时留意它的 exports 字段是否把两种格式都暴露给了同一批使用者。
原生 ESM 不等于可以不要构建。 浏览器不认 TypeScript、JSX,也没有 tree-shaking 和环境变量替换。模块数量上百、需要按路由拆包的项目,构建步骤省不掉。原生 ESM 更适合内部工具、小页面,或者作为开发期的加载方式。
今天就能动手的实验
下面这几件事一个下午能做完,做完再回头看上面的表格,很多结论就不用背了。
- 起一个本地静态服务,复现开头的
count例子,确认打印 0 和 1;再给导入的名字赋值,记录报错文案。 - 写一对互相导入的模块,分别用
const、var、函数声明导出,三次刷新记录结果,把三种表现写进自己的笔记。 - 在三个有依赖关系的模块顶层各加一行带时间戳的日志,观察顺序;再把其中一个改成动态导入,比较 Network 面板里请求出现的时机。
- 建一个带顶层 await 的模块,让它被两个模块依赖,观察控制台顺序和页面首屏时间的变化。
- 找一个你项目里「删了会出问题」的文件,在它顶层加日志,确认它是不是被副作用导入的。
小结
const/let 绑定。下一篇讲打包器内部。这一篇里那句「打包器把整张图折成几个文件」只是带过,实际上怎么折、按什么边界折、折完之后哪些语义变了,又是另一套机制。你在浏览器里看到的模块图,到了生产环境往往已经面目全非,理解折叠过程,才能解释「本地好好的,线上为什么不一样」。