用途
该技能用于检测并解决 TypeScript/JavaScript 项目中的循环导入依赖问题。循环依赖会出现在模块 A 导入模块 B、而 B 又直接或间接导入 A 的情况下。TypeScript 编译可以通过,但运行时某个导入会因模块尚未完成初始化而求值为 undefined。
触发场景
常见错误信息:
- ReferenceError: Cannot access 'UserService' before initialization
- TypeError: Cannot read properties of undefined (reading 'create')
- TypeError: (0 , _service.doSomething) is not a function
提示存在循环导入的症状:
- 导出确实存在,但导入却是 undefined
- 错误只在运行时出现,不在 TypeScript 编译期间出现
- 移动 import 语句会改变哪一个导入变为 undefined
- 测试失败但应用正常(或相反)
- 在文件顶部添加 console.log 会改变行为
第一步:检测循环
使用工具可视化依赖关系:
# 安装 madge
npm install -g madge
# 查找循环依赖
madge --circular --extensions ts,tsx src/
# 生成可视化图
madge --circular --image graph.svg src/
或使用 TypeScript 编译器:
# 检查循环(需要 tsconfig 设置)
npx tsc --listFiles | head -50
第二步:识别模式
常见的循环依赖模式:
- 模式 A:服务对服务:services/userService.ts → services/orderService.ts → services/userService.ts
- 模式 B:类型导入:types/user.ts → types/order.ts → types/user.ts
- 模式 C:索引 barrel 文件:components/index.ts → components/Button.tsx → components/index.ts
第三步:解决策略
策略 1:抽取共享依赖
处理前:
// userService.ts
import { OrderService } from './orderService';
export class UserService { ... }
// orderService.ts
import { UserService } from './userService';
export class OrderService { ... }
处理后:
// types/interfaces.ts(新文件——不从 services 导入)
export interface IUserService { ... }
export interface IOrderService { ... }
// userService.ts
import { IOrderService } from '../types/interfaces';
export class UserService implements IUserService { ... }
策略 2:依赖注入
// orderService.ts
export class OrderService {
constructor(private userService: IUserService) {}
// 而不是直接导入 UserService
}
// main.ts
const userService = new UserService();
const orderService = new OrderService(userService);
策略 3:动态导入
// 只在需要时导入,而不是在模块顶层
async function processOrder() {
const { UserService } = await import('./userService');
// ...
}
策略 4:使用仅类型导入
如果只需要类型(而非值),使用仅类型导入:
// 这不会创建运行时依赖
import type { User } from './userService';
策略 5:重构 barrel 文件
处理前(有问题):
// components/index.ts
export * from './Button';
export * from './Modal'; // Modal 从 './index' 导入 Button
处理后:
// components/Modal.tsx
import { Button } from './Button'; // 直接导入,而非从 index 导入
第四步:防止未来出现循环
添加到 CI/构建流程:
// package.json
{
"scripts": {
"check:circular": "madge --circular --extensions ts,tsx src/"
}
}
或配置 ESLint:
// .eslintrc.js
module.exports = {
plugins: ['import'],
rules: {
'import/no-cycle': ['error', { maxDepth: 10 }]
}
};
验证
- 运行 madge --circular src/ ——应报告无循环
- 运行测试套件——之前为 undefined 的导入应正常工作
- 删除 node_modules 并重新安装——应用仍应正常工作
- 生产构建——无运行时错误
示例
问题:OrderService 在 UserService 中被导入时为 undefined
检测:
$ madge --circular src/
Circular dependencies found!
src/services/userService.ts → src/services/orderService.ts → src/services/userService.ts
修复:抽取共享接口
// 新增:src/types/services.ts
export interface IOrderService {
createOrder(userId: string): Promise<Order>;
}
// 修改:src/services/userService.ts
import type { IOrderService } from '../types/services';
export class UserService {
constructor(private orderService: IOrderService) {}
}
// 修改:src/services/orderService.ts
// 不再导入 UserService
export class OrderService implements IOrderService {
async createOrder(userId: string): Promise<Order> { ... }
}
注意事项
- TypeScript 的 import type 很有用——它在运行时被擦除,不会造成循环
- Barrel 文件(index.ts)是意外循环的常见来源
- 当存在循环时,文件中导出的顺序可能有影响
- Jest/Vitest 处理模块解析的方式可能与打包工具不同
- 某些打包工具(Webpack、Vite)对循环的处理比其他工具更好
- require() 有时会掩盖 import 暴露出的循环依赖问题