JavaScript 模块循环依赖时变量值为 undefined 的问题

JavaScript 开发中，当模块 A 依赖模块 B，同时模块 B 又依赖模块 A 时，会形成循环依赖。如果代码执行时机不当，开发者经常会发现导入的变量值为 undefined，导致程序报错。本文将通过具体复现步骤，分析其背后的加载机制，并提供三种切实可行的解决方案。

1. 复现问题：构建循环依赖场景

首先，我们需要构建一个最简单的循环依赖场景，观察变量值的变化。我们将使用 var 声明变量，因为它具有变量提升的特性，能最直观地展示“变量存在但值为 undefined”的现象（在现代 ES Modules 中，let 和 const 此时通常会抛出 ReferenceError，但原理相同）。

创建 文件 moduleA.js，输入以下代码：

// moduleA.js
import { bValue } from './moduleB.js';

console.log('Module A: 开始执行');
export var aValue = '我是 A 的值';
console.log('Module A: bValue 的值是', bValue);

创建 文件 moduleB.js，输入以下代码：

// moduleB.js
import { aValue } from './moduleA.js';

console.log('Module B: 开始执行');
export var bValue = '我是 B 的值';
console.log('Module B: aValue 的值是', aValue);

创建 入口文件 main.js，输入以下代码：

// main.js
import { aValue } from './moduleA.js';
console.log('Main 入口:', aValue);

运行 该文件。在终端中执行 node main.js。

观察控制台输出，结果如下：

Module A: 开始执行
Module B: 开始执行
Module B: aValue 的值是 undefined
Module A: bValue 的值是 我是 B 的值
Main 入口: 我是 A 的值

可以看到，在 Module B 中打印 aValue 时，其值为 undefined。

2. 分析原因：理解模块加载机制

要理解这个问题，必须深入 ES Modules 的执行顺序。ES Modules 采用的是“实时绑定”（Live Binding）机制，但在初始化阶段，执行顺序是线性的。

当 main.js 导入 moduleA.js 时，发生了以下步骤：

1. 解析 引擎开始评估 moduleA.js。
2. 执行 引擎遇到第一行代码 import { bValue } from './moduleB.js'。
3. 递归 由于 moduleA 尚未执行完毕，引擎暂停 moduleA 的执行，转而去加载并评估 moduleB.js。
4. 深层依赖 在 moduleB.js 中，遇到 import { aValue } from './moduleA.js'。此时 moduleA 已经在加载队列中，但它处于“未完成初始化”的状态。
5. 读取 moduleB.js 继续执行，尝试访问 aValue。虽然变量 aValue 的空间已经分配（由于 var 的变量提升），但 moduleA 中的赋值语句 export var aValue = ... 还未执行到。因此，读取到的值是初始值 undefined。

下图清晰地展示了这一“死锁”般的执行流程：

3. 解决方案 1：延迟导入

这是最快速的修复方法。核心思路是打破“顶层执行”的循环。将导入语句移到函数内部，使其只有在函数被调用时才会执行，从而推迟了模块的加载时机。

修改 moduleA.js，删除顶部的 import，将其移入函数内部：

// moduleA.js
export var aValue = '我是 A 的值';

export function printB() {
    // 动态导入，仅在函数调用时执行
    const { bValue } = require('./moduleB.js'); 
    // 注意：如果使用 ES6 import 语法，必须放在顶层。
    // 这里演示逻辑，实际 ES6 环境推荐使用方案 2 或 3
    console.log('Module A: 此时 bValue 的值是', bValue);
}

console.log('Module A: 初始化完成');

注意：标准的 ES6 import 语法必须位于文件顶层。如果在 ES6 环境下，此方案通常意味着改变代码结构（例如：不再在顶层直接引用对方，而是在运行时交互）。如果在 Node.js 环境且允许 CommonJS 互操作，可以使用 require() 实现延迟加载。

4. 解决方案 2：依赖注入

这是软件工程中更推荐的做法，符合“依赖倒置原则”。模块 A 不再主动去导入模块 B，而是通过函数参数接收它需要的数据或方法。

修改 moduleB.js，移除对 moduleA 的导入，改为导出一个接收参数的函数：

// moduleB.js
export var bValue = '我是 B 的值';

// 不再 import { aValue }，而是通过参数接收
export function logValue(otherValue) {
    console.log('Module B: 接收到的值是', otherValue);
}

修改 moduleA.js，在调用 B 的函数时传入 aValue：

// moduleA.js
import { logValue } from './moduleB.js';

export var aValue = '我是 A 的值';

// 等待 A 初始化完毕后，再将数据传给 B
logValue(aValue); 

运行 main.js。此时输出将正常，因为 aValue 在传入 logValue 时已经完成了赋值。

5. 解决方案 3：提取公共模块

如果 A 和 B 相互依赖是因为它们都需要某些公共功能（例如工具函数），最好的办法是将这部分逻辑提取到第三个模块 common.js 中。这彻底消除了循环依赖的结构。

创建 新文件 common.js：

// common.js
export function helper() {
    return '公共工具函数';
}

修改 moduleA.js，使其只依赖 common.js：

// moduleA.js
import { helper } from './common.js';
export var aValue = helper() + ' - A';

修改 moduleB.js，使其也只依赖 common.js：

// moduleB.js
import { helper } from './common.js';
export var bValue = helper() + ' - B';

此时，依赖关系从 A <-> B 变成了 A <- C -> B，结构清晰且无风险。

6. 方案对比与选择

为了帮助您在实际项目中做出最佳选择，下表总结了上述三种方案的特点：