前端项目越做越大，模块之间的引用关系会逐渐从一棵树变成一张网。Webpack 在打包时会对所有 import 和 require 建立模块依赖图，当它发现 a.js 依赖 b.js，b.js 又依赖 a.js 时，就会在控制台打印一条 Circular dependency detected 警告。这个警告本身不会终止构建，也不会必然造成功能异常，但它意味着某些模块在初始化阶段可能拿到另一个模块尚未完成导出的值。
要理解这个警告，关键要看 ES Modules 和 CommonJS 的加载差异。Webpack 对两种模块语法都做了兼容，但在代码被打包进同一个运行时后，模块初始化顺序仍然遵循语言本身的语义。以 ES Modules 为例，import 语句是静态声明的，即使写在文件底部，也会在模块执行前完成依赖求值。如果两个模块在顶层互相读取对方的导出值，就很容易出现 undefined。
循环依赖警告是怎么产生的
循环依赖不是一个 Webpack 专属问题，Node.js、Rollup、Vite 等工具同样会遇到。Webpack 的特别之处在于它会在构建阶段主动扫描依赖图，输出一条带模块路径的警告信息。比如下面这段代码会触发循环依赖：
// a.js
import { bValue } from './b';
export const aValue = 'A';
console.log(bValue);
// b.js
import { aValue } from './a';
export const bValue = 'B' + aValue;
入口文件如果先加载 a.js，那么 Webpack 会先进入 a.js 的执行阶段，发现它依赖 b.js，于是转去执行 b.js；b.js 又需要 a.js 中的 aValue，但 a.js 此时还没有执行到 export 那一行，因此 b.js 拿到的 aValue 是 undefined。最终 bValue 变成 Bundefined，而 a.js 后续打印出来的 bValue 已经是一个被污染的字符串。
还有一种情况是依赖环里的模块并没有在顶层互相访问，而是把访问动作放到了函数内部。这时警告仍然存在，但运行结果往往是正常的，因为函数被调用时所有模块都已经初始化完成。这正是很多开发者觉得警告可以忽略的原因。问题在于，这种正常依赖了开发时的加载顺序和调用时机，一旦某个入口顺序变化，或者懒加载提前执行，原本正常的功能就可能突然出现 undefined，排查起来非常隐蔽。
如何快速定位循环依赖链路
Webpack 输出的警告已经包含一条路径，但它展示的往往是最短环路，真实项目中的依赖链可能更长、更复杂。只看到 a.js 到 b.js 的提示，不足以判断应该改哪个模块。为了找到更完整的循环，可以把 Webpack 的 stats 数据导出成 JSON 文件再分析：
npx webpack --json > stats.json
这份 stats.json 中包含 modules 数组，每个模块都有 reasons 和 issuer 信息。reasons 描述谁依赖这个模块，issuer 是上一级导入者。通过遍历这些字段，可以看到依赖环中的所有节点。不过手写脚本分析成本偏高，更推荐直接用 madge 这样的工具对源码做静态扫描：
npx madge --circular src/index.js
madge 会列出所有循环依赖的完整链路，不限于 Webpack 最终打包用的入口。如果只在 TypeScript 或 Babel 项目中工作，还可以在 ESLint 里启用 import/no-cycle 规则。它能在开发阶段直接标红产生循环的 import 语句，比打包后再看警告更早发现问题。
// .eslintrc.js
module.exports = {
rules: {
'import/no-cycle': ['error', { maxDepth: 20 }]
}
};
定位时要注意区分两种循环：一种是模块顶层互相读取值，这种危险最高；另一种是只存在引用关系，但没有在初始化阶段使用对方。前者的具体表现通常是页面加载后某些常量、配置、单例对象为 undefined，后者则可能只是构建提示。把循环链路和运行时错误绑定起来看，才能判断优先级。
解决循环依赖的常用方案
第一种也是最推荐的做法是抽出公共模块。很多循环依赖的本质是两个人同时依赖对方的能力，却没有把共同需要的部分下沉。比如 a.js 只是想使用 b.js 中的格式化方法，b.js 又需要 a.js 中的常量，这时可以把常量和格式化方法分别抽到独立的 constants.js 和 formatter.js 中，让 a.js 与 b.js 都变成单向依赖。
// constants.js
export const DEFAULT_PAGE_SIZE = 20;
// formatter.js
export function formatDate(date) {
return date.toISOString();
}
// a.js
import { DEFAULT_PAGE_SIZE } from './constants';
import { formatDate } from './formatter';
export function renderA() {
return formatDate(new Date()) + DEFAULT_PAGE_SIZE;
}
// b.js
import { formatDate } from './formatter';
export function renderB() {
return formatDate(new Date());
}
这个改动看似简单，实际需要判断哪些导出被双方共用，以及被引用的频率。公共模块要保持稳定，避免抽象过度。如果只是两个文件之间的小范围交互，抽离一个公共模块就能立刻消除警告，同时让模块职责更加清晰。
第二种办法是延迟导入。循环依赖只有在模块初始化阶段同步求值时才危险，如果把对另一个模块的访问放进函数内部，就能绕开初始化顺序问题。使用动态 import 可以做到真正的按需加载：
// a.js
export async function loadAndRender() {
const { renderB } = await import('./b');
return renderB();
}
动态 import 返回 Promise，所以它不会阻塞当前模块初始化，也不会要求在 a.js 执行前先完整加载 b.js。不过这种方法会把同步调用变成异步调用，如果上层代码期望同步返回，就需要做相应调整。在 CommonJS 模块里也可以使用函数内 require 达到类似效果，但写法上混合模块语法可能让维护者困惑，建议只在明确需要打破同步初始化环时使用。
第三种方案是重构模块边界，用事件或回调解耦。假设两个模块互相依赖是因为一个模块要通知另一个模块做某些事，例如编辑器模块通知预览模块刷新，预览模块又需要读取编辑器模块的状态，这时可以引入一个轻量事件总线：
// eventBus.js
const listeners = {};
export function on(name, cb) {
(listeners[name] || (listeners[name] = [])).push(cb);
}
export function emit(name, data) {
(listeners[name] || []).forEach(function(cb) {
cb(data);
});
}
编辑器模块只依赖事件总线并 emit 事件，预览模块也只依赖事件总线并 on 监听。两者不再直接 import 对方，自然没有循环依赖。这个方案的额外收益是模块之间的耦合变低，但事件过多时会降低代码可读性，调试时也更难追踪调用来源，因此适合模块边界相对稳定的场景，而不是全部都用事件解决。
从工程规范上预防循环依赖
依赖环一旦出现，修复往往需要动模块边界，改起来越晚成本越高。与其每次打包后手动清警告，不如把约束前移到编码阶段。常见的做法是给文件夹设置依赖方向，比如约定 utils 不能依赖 components，components 不能依赖 pages。团队内部形成一致后，可以在 ESLint 配置里通过 import/no-cycle 设置 error 级别，把新增循环直接拦截在本地开发阶段。
另一个容易制造循环依赖的是 barrel file，也就是 index.js 统一导出的写法。它可以让外部模块 import 路径更短，但如果在同一目录内部，Button 组件为了引用 Modal，不是直接 import 具体文件，而是 import 到目录下的 index.js，就很容易形成隐式循环。处理办法是组件内部引用兄弟组件时使用相对具体路径，不要通过 index.js 中转。
// components/index.js
export { Button } from './Button';
export { Modal } from './Modal';
// Button.js 避免这样引用
// import { Modal } from './index';
// 推荐使用具体路径
import { Modal } from './Modal';
如果项目已经存在历史循环，也不必一次性全部清零。可以先用 madge 生成循环清单，按影响范围排序，优先处理包含工具函数、常量、单例服务的高危环。对于只存在于叶子组件之间的低风险环，可以安排在下一次重构中逐步拆解。更重要的是建立 CI 检查，让每次提交都能发现新增循环，避免问题重新堆积。
循环依赖不是构建工具的 bug，而是模块设计出现了环。Webpack 的警告只是帮我们把这种设计问题暴露出来。理解了初始化顺序和模块依赖方向之后，解决和预防循环依赖就变成一件有章可循的事。
Webpack循环依赖循环依赖解决模块依赖管理修改时间：2026-09-18 19:19:05