2025-12-11-【架构】vite页面聚合循环依赖

在 Vite/Rollup 编译过程中，循环依赖（Circular Dependency） 往往不是导致直接崩溃的“死罪”，但它会导致**页面聚合（Chunking）**时出现逻辑错误：比如某个变量为 undefined、模块初始化失败，或者打包产物出现巨大的重复代码。

以下是针对 Vite 项目中循环依赖问题的全流程深度解析：

---

1. 发现问题：常见的报错信息

循环依赖在开发阶段（esbuild）和生产打包（Rollup）时表现不同。

• 报错信息 A (Runtime Error)：
  Uncaught ReferenceError: Cannot access 'XXX' before initialization
  这是最典型的报错，通常发生在 const 或 class 被循环引用时。
• 报错信息 B (Warning)：
  Circular dependency: src/hooks/useUser.ts -> src/utils/auth.ts -> src/hooks/useUser.ts
  Vite 在 npm run build 时会直接在终端输出这类警告。
• 报错信息 C (Memory Leak / Infinite Loop)：
  页面卡死，或者在编译阶段 Rollup 提示 Maximum call stack size exceeded（通常出现在组件自引用且没有终止条件时）。

---

2. 问题定位：精准捕捉路径

方法一：利用 Vite 终端日志

Vite 生产构建基于 Rollup，它会默认打印出循环引用的链条。

技巧：如果警告太多被淹没了，可以使用 npm run build > build.log 将日志导出查找 Circular 关键字。

方法二：使用插件检测 (推荐)

在 vite.config.ts 中引入插件，可以在开发阶段就强制报错：

// 安装：npm i vite-plugin-checker -D
import checker from "vite-plugin-checker";

export default {
  plugins: [
    checker({
      // 开启 eslint 检查，并在 eslint 中配置 import/no-self-import 和 import/no-cycle
      eslint: { lintCommand: 'eslint "./src/**/*.{ts,tsx}"' },
    }),
  ],
};

方法三：可视化分析

使用 rollup-plugin-visualizer 插件生成统计图，观察哪些模块被异常聚合在一起。如果两个原本不相关的 Chunk 互相包含，通常就是循环依赖在作祟。

---

3. 原因分析：为什么会产生？

在微前端或 Lerna 多包结构中，循环依赖通常由以下模式引起：

• 模式 A：A 引用 B，B 引用 A

• AuthService.ts 需要调用 UserStore.ts 获取用户信息。

• UserStore.ts 的初始化逻辑里又调用了 AuthService.ts 来检查登录状态。

• 模式 B：桶文件（Index.ts）陷阱

• 你有一个 src/components/index.ts 导出了所有组件。

• 组件 A 引用了 index.ts 中的组件 B，而组件 B 又引用了 index.ts 中的组件 A。

• 这是 Vite 项目中最隐蔽、最高频的循环依赖原因。

---

4. 解决方案：从架构层面破局

根据复杂程度，由浅入深采用以下策略：

策略一：解耦公共部分 (Common Extraction)

将 A 和 B 共同依赖的代码提取到第三个模块 C 中。

• 修改前：A ⇄ B
• 修改后：A → C, B → C

策略二：延迟引用 (Lazy Loading / Dynamic Import)

通过动态 import() 打断同步依赖链，这会让 Vite 将其拆分为不同的 Chunk。

// 在 B.ts 中
export const doSomething = async () => {
  const { functionFromA } = await import("./A"); // 运行时加载，打破编译时循环
  functionFromA();
};

策略三：移除“桶文件” (Barrel Files)

尽量避免在组件库内部使用 index.ts 进行中转引用。

• 错误：import { Button } from '../index'
• 正确：import { Button } from './Button'

策略四：依赖注入 (Dependency Injection)

不再在模块顶层直接 import，而是通过函数参数或配置项传入。

// AuthService.ts
export const initAuth = (userStore: any) => {
  // 通过参数获取，而不是 import
};

---

5. 验证与预防

1. 代码规范：在 ESLint 中开启 eslint-plugin-import 的 no-cycle 规则。
2. 构建测试：在 CI/CD 流程中增加 npm run build 步骤，并设置 logLevel: 'error'，确保任何循环依赖警告都能阻断合并。
3. Vite 配置优化：
   在 vite.config.ts 中调整 Rollup 的手动分包策略，强制隔离某些模块：

build: {
  rollupOptions: {
    output: {
      manualChunks(id) {
        if (id.includes('node_modules')) return 'vendor';
        // 发现循环严重的地方，手动拆分
      }
    }
  }
}

---

💡 总结

循环依赖本质上是模块职责划分不清晰的产物。处理它的过程也是一次重构代码、理清业务逻辑的机会。