如何解决Node.js循环依赖问题？策略与实践详解

Node.js的CommonJS模块系统在加载模块时会缓存已经加载过的模块，当两个或多个模块互相引用对方时，就会产生循环依赖。这种情况下，模块可能无法获取到对方完整的导出内容，进而引发运行时的错误。

循环依赖的产生原因

Node.js在执行模块代码时，会先执行模块顶层代码，遇到require语句时会暂停当前模块的执行，去加载被引用的模块。如果被引用的模块又反过来引用当前模块，此时当前模块还没有执行完成，缓存中存储的只是当前模块已经执行部分的结果，就会出现依赖不完整的情况。

比如下面的两个模块，就形成了典型的循环依赖：

// a.js
console.log('a模块开始执行');
const b = require('./b.js');
console.log('在a模块中获取b的变量:', b.bVar);
exports.aVar = '我是a模块的变量';
console.log('a模块执行结束');

// b.js
console.log('b模块开始执行');
const a = require('./a.js');
console.log('在b模块中获取a的变量:', a.aVar);
exports.bVar = '我是b模块的变量';
console.log('b模块执行结束');

执行a.js后，输出结果如下：

a模块开始执行
b模块开始执行
在b模块中获取a的变量: undefined
b模块执行结束
在a模块中获取b的变量: 我是b模块的变量
a模块执行结束

可以看到在b模块中引用a模块时，a模块还没有执行到导出aVar的代码，所以获取到的是undefined。

解决循环依赖的常用策略

1. 调整模块结构，消除循环引用

这是最根本的解决方式，循环依赖往往意味着模块的职责划分不够合理。可以把两个模块共同依赖的逻辑抽离到第三个独立的模块中，让原来的两个模块都去引用这个新的模块，从而打破循环。

比如上面的a和b模块都依赖对方的变量，可以把公共的逻辑抽成c模块：

// c.js
exports.commonVar = '公共变量';

// a.js
const c = require('./c.js');
exports.aVar = '我是a模块的变量' + c.commonVar;

// b.js
const c = require('./c.js');
exports.bVar = '我是b模块的变量' + c.commonVar;

2. 延迟导入，在函数内部使用require

如果循环依赖暂时无法调整结构，可以把require语句放到函数内部，等到函数被调用时再去加载依赖模块，此时外层模块的初始化代码已经执行完成，导出的内容已经完整。

// a.js
exports.aVar = '我是a模块的变量';
exports.getBVar = function() {
  const b = require('./b.js');
  return b.bVar;
};

// b.js
exports.bVar = '我是b模块的变量';
exports.getAVar = function() {
  const a = require('./a.js');
  return a.aVar;
};

3. 使用依赖注入

不要在模块顶层直接引用依赖，而是通过函数参数传入需要的依赖，这样可以在模块初始化完成之后再把依赖传入，避免循环引用的问题。

// a.js
exports.init = function(bModule) {
  console.log('a模块获取到b的内容:', bModule.bVar);
  return {
    aVar: '我是a模块的变量'
  };
};

// b.js
exports.init = function(aModule) {
  console.log('b模块获取到a的内容:', aModule.aVar);
  return {
    bVar: '我是b模块的变量'
  };
};

// main.js
const a = require('./a.js');
const b = require('./b.js');
const aInstance = a.init(b);
const bInstance = b.init(aInstance);

4. 使用ES模块的动态导入

如果项目使用ES模块，可以使用import()动态导入语法，动态导入返回的是Promise，会在模块执行完成之后才解析，能够避免循环依赖的问题。

// a.mjs
export const aVar = '我是a模块的变量';
export const getBVar = async () => {
  const b = await import('./b.mjs');
  return b.bVar;
};

// b.mjs
export const bVar = '我是b模块的变量';
export const getAVar = async () => {
  const a = await import('./a.mjs');
  return a.aVar;
};

不同策略的适用场景

总结

Node.js的循环依赖问题本质上和模块加载机制相关，解决时优先选择调整模块结构的方式，从根源上消除循环引用。如果暂时无法重构，可以根据项目情况选择延迟导入、依赖注入或者ES模块动态导入的方式。在开发过程中，合理划分模块职责，避免模块之间的过度耦合，能够有效减少循环依赖的出现概率，提升项目的可维护性。

Node.js循环依赖模块系统依赖注入CommonJS修改时间：2026-06-11 04:42:24