模块化：从CommonJS到ESM，模块依赖循环引用的坑你踩过吗？

第一次在 Node 项目里遇到循环依赖，我盯着一个 undefined 纳闷了半天：明明在 a.js 里导出了函数，b.js 却死活拿不到。后来才知道，这不是代码写错了，而是模块加载机制在循环引用时露出的“半成品”状态。从 CommonJS 到 ESM，模块化方案换了一代又一代，但循环依赖这个坑，依然有人前赴后继地踩。

CommonJS 的“半成品”导出

CommonJS 的 require 是同步加载、执行、缓存。当 a.js 依赖 b.js，而 b.js 又回头依赖 a.js 时，Node 不会报错，而是把 a.js 当前已经执行到的 module.exports 先交给 b.js。问题在于，此时 a.js 可能还没执行完，导出的对象可能只是个空壳。

// a.js
exports.done = false;
const b = require('./b');
console.log('in a, b.done =', b.done);
exports.done = true;

// b.js
exports.done = false;
const a = require('./a');
console.log('in b, a.done =', a.done); // false，而不是 true
exports.done = true;

b.js 里拿到的 a 是未完成的 exports，所以 a.done 还是 false。更隐蔽的是，如果 a.js 后来用 module.exports = {...} 整体替换，b.js 手里拿到的还是旧引用，永远不会更新。解决办法通常是把 require 延迟到函数内部，或者让模块只导出函数，不在顶层消费依赖。

ESM 的 live binding 不是万能药

ESM 看起来更“高级”：静态分析、依赖图先建立、再实例化、最后执行。导出是 live binding，值会联动。但循环依赖时，它照样能让你翻车，而且报错更晚、更难查。

// a.mjs
import { b } from './b.mjs';
export const a = 'a';
console.log(b);

// b.mjs
import { a } from './a.mjs';
export const b = a; // ReferenceError: Cannot access 'a' before initialization

因为 const / let 没有初始化提升，b.mjs 在顶层读取 a 时会撞上 TDZ。而函数声明有提升，所以循环依赖里“导出函数”往往能侥幸跑通，但函数内部如果访问了尚未初始化的变量，调用时依然可能炸。live binding 能保证你稍后拿到最新值，却不能保证“此刻”就能安全访问。

混用 CJS 和 ESM 更酸爽

Node 里 ESM 可以 import CommonJS，CommonJS 也能有限地 require ESM，但两者加载语义不同。一旦循环依赖跨越两种模块系统，默认导出、命名导出、缓存时机全搅在一起，排查难度直接翻倍。如果项目正在迁移，尽量统一模块系统；实在要混用，用动态 import() 打破同步循环，别让静态依赖图绕成死结。

排查与规避：让依赖图保持单向

工具能帮你省不少事：madge --circular src 可以扫出循环依赖，eslint-plugin-import 的 no-cycle 能在提交前报警，Webpack 也有 circular-dependency-plugin。但工具只是报警器，真正的解法在架构：

• 保持依赖单向，分层清晰，上层依赖下层，下层绝不反向依赖；
• 把共享类型、常量、工具函数抽到第三个模块；
• 用依赖注入、事件总线或注册表解耦；
• 慎用 barrel 文件，index.ts 互相导入是循环依赖的重灾区；
• 延迟加载：函数内 require，或动态 import()。

写在最后

循环依赖不是语言 bug，而是设计信号。CommonJS 给你一个未完成的 exports，ESM 给你 TDZ 和 live binding 的错觉，本质上都在提醒：模块之间的依赖关系开始纠缠了。理解加载顺序，保持依赖图尽量是一张有向无环图，比记住任何“奇技淫巧”都管用。下次再看到 undefined 或 Cannot access before initialization，先别急着改代码，画一画依赖图，坑可能就在那个环上。