Skip to content
概述
Nest 的依赖注入容器在应用启动阶段会检查所有模块的导入关系以及每个提供者的构造签名。当某个提供者所需的依赖无法解析，或者解析路径形成闭环，错误会在启动时直接暴露出来。
最常见的报错形式有两种：
Nest can't resolve dependencies of the X (?, ...). Please make sure that the argument Y at index [0] is available in the current context.以及明确带有关键字的：
Error: Circular dependency detected in ...无论是“无法解析依赖”还是“检测到循环”，排查的入口都在错误信息中列出的类名和参数索引。先找到出错的提供者属于哪个模块，然后检查该模块的 imports 是否形成了环。如果模块之间的导入关系是单向无环的，再检查提供者构造函数的参数是否引用了尚未初始化的类。
以下内容会依次涉及循环依赖、全局模块、请求作用域、动态模块异步配置以及多数据库连接，最后讨论在这些限制下可以做出的设计取舍。
循环依赖
成因
循环依赖指的是两个类在构造过程中相互依赖。在 Nest 里，这种情况通常有两种成因：
- 模块之间通过
imports数组形成环路。 - 两个提供者在构造函数的参数中相互注入，且两个提供者跨越了模块边界。
下面是一个典型的模块环例子：
typescript
// a.module.ts
@Module({
imports: [BModule],
providers: [AService],
exports: [AService],
})
export class AModule {}
// b.module.ts
@Module({
imports: [AModule],
providers: [BService],
exports: [BService],
})
export class BModule {}当 BModule 试图导入 AModule 时，AModule 又在解析 BModule，Nest 无法决定先初始化哪一个，启动时就会抛出类似 Nest can't resolve dependencies of the BService 的错误。
构造参数层面的循环同样会导致启动失败：
typescript
@Injectable()
export class UserService {
constructor(private readonly authService: AuthService) {}
}
@Injectable()
export class AuthService {
constructor(private readonly userService: UserService) {}
}UserService 需要 AuthService 来构造，但 AuthService 反过来又要 UserService，容器在实例化任何一个时都会卡住。错误信息往往会指向某个参数索引，反映出依赖链的断裂。
forwardRef
forwardRef 的目的是打破模块解析的即时性。它允许 Nest 在被引用类还未定义时先记录一个引用，等到真正需要该类的实例时才去解析。
模块层面用法：
typescript
// a.module.ts
@Module({
imports: [forwardRef(() => BModule)],
providers: [AService],
exports: [AService],
})
export class AModule {}
// b.module.ts
@Module({
imports: [forwardRef(() => AModule)],
providers: [BService],
exports: [BService],
})
export class BModule {}提供者层面也可以同样处理：
typescript
@Injectable()
export class UserService {
constructor(
@Inject(forwardRef(() => AuthService))
private readonly authService: AuthService,
) {}
}forwardRef 让 Nest 在调用 require() 或等价操作时不立即对目标类求值，而是推迟到实际构造阶段。这样就能绕开启动时的死锁，但循环本身依然存在，只是被推迟了暴露的时机。
模块拆分
更持久的方案是把两个模块共用的部分抽到一个独立的基层模块中，让依赖方向变成单向。
假设 UserService 和 AuthService 都依赖同一个日志服务 LoggerService，而它们之间不再直接引用，模块结构就会变成：
typescript
// common.module.ts — 基层模块
@Module({
providers: [LoggerService],
exports: [LoggerService],
})
export class CommonModule {}
// user.module.ts
@Module({
imports: [CommonModule],
providers: [UserService],
exports: [UserService],
})
export class UserModule {}
// auth.module.ts
@Module({
imports: [CommonModule],
providers: [AuthService],
exports: [AuthService],
})
export class AuthModule {}这时 UserModule 和 AuthModule 都只依赖于 CommonModule，没有形成环。如果业务逻辑确实需要跨模块调用，可以让其中一个模块依赖另一个，但依赖方向必须一致，不能来回引用。
forwardRef 解决的是实例化顺序的僵局，模块拆分解决的是结构上的循环。实际项目中，先通过 forwardRef 让程序跑起来，再规划模块边界来消除环，是一种常见的演进路径。
全局模块
@Global() 与隐式依赖
@Global() 装饰器使一个模块导出的提供者无需在消费者模块的 imports 中显式声明，即可在整个应用中被注入。
typescript
@Global()
@Module({
providers: [ConfigService],
exports: [ConfigService],
})
export class CommonModule {}其他模块可以直接在构造函数参数里使用 ConfigService，而不需要先导入 CommonModule：
typescript
@Injectable()
export class SomeService {
constructor(private readonly config: ConfigService) {}
}这减少了 imports 数组的书写量，但也带来了隐式依赖。任何一个模块都能拿到全局提供者，但代码里缺少那条明确的导入语句，阅读者很难直接看出某条依赖的源头。隐式依赖还会给测试和替换增加麻烦：如果单元测试需要换掉全局服务，必须知道这个服务是通过全局模块提供的，否则替换的 mock 可能根本不会生效。
收敛为显式导入
当全局模块的提供者仅被少数几个模块使用时，可以移除 @Global() 装饰器，并在需要的模块中显式导入该模块。
typescript
// common.module.ts — 去掉 @Global()
@Module({
providers: [ConfigService],
exports: [ConfigService],
})
export class CommonModule {}
// user.module.ts
@Module({
imports: [CommonModule], // 显式导入
providers: [UserService],
})
export class UserModule {}显式导入之后，依赖来源可以直接通过 imports 数组找到，这个模块的内部实现也更容易替换或 mock。
只有在提供者真正通用，且几乎没有替换需求时（比如应用级的日志服务、跨越所有业务模块的配置中心），才适合保留 @Global() 标记。即便如此，仍建议限制全局模块的数量，避免让依赖图变成一张全连接网。
请求作用域
作用域类型与性能开销
Nest 的注入作用域分为三种：
DEFAULT（单例）：整个应用生命周期内只创建一个实例。REQUEST（请求级）：每个 HTTP 请求创建一个新实例。TRANSIENT（瞬态）：每次注入都创建一个新实例。
当提供者被声明为请求作用域时，Nest 无法为它和它的依赖链上的其他提供者使用缓存。每个请求都会走一遍完整的实例化路径，包括所有间接依赖，导致栈深加大、GC 压力上升。
官方文档给出的性能警告是：使用请求作用域提供者会对应用性能产生负面影响。原因就在于单例缓存被绕过，原本只需要创建一次的对象，现在每个请求都要重新创建并最终回收。
尤其需要注意：如果一个被请求作用域的提供者所依赖的服务是单例，那这个单例也会被按请求重建，因为 Nest 的做法是“如果请求链路中任何一个提供者是请求作用域，那么整条链路都按请求来处理”。这会让本可以复用的对象也被反复创建。
保持单例并传递请求上下文
当业务需要获取当前请求的信息（如请求头、用户 IP），不建议将整个服务升级为请求作用域。有两种更经济的手段。
单例服务 + 方法参数
保持提供者为默认单例，把请求上下文数据作为方法参数传入：
typescript
@Injectable()
export class AuditService {
log(action: string, request: Request) {
console.log(request.ip, action);
}
}
@Controller('users')
export class UserController {
constructor(private readonly audit: AuditService) {}
@Get()
findAll(@Req() request: Request) {
this.audit.log('fetch all users', request);
return [];
}
}AuditService 是单例，不需要每次请求创建新实例。上下文数据只在需要时显式传入。
仅在必要时使用 @Inject(REQUEST)
如果确实需要在整个服务的方法中频繁使用请求信息，并且不适合通过参数传递，可以把提供者声明为请求作用域，并通过 @Inject(REQUEST) 注入原生请求对象：
typescript
import { REQUEST } from '@nestjs/core';
@Injectable({ scope: Scope.REQUEST })
export class AuditService {
constructor(@Inject(REQUEST) private readonly request: Request) {}
log(action: string) {
console.log(this.request.ip, action);
}
}此时这一条链路上的所有依赖都会变成请求作用域，开销随之上升。应该把这类提供者的范围限制在真正需要的地方，不要让依赖链无限制地扩散。
动态模块异步配置与多数据库
forRootAsync 中的依赖声明
动态模块的 registerAsync 或 forRootAsync 方法允许通过 useFactory 异步获取配置，但 imports 中列出的模块初始化会先于 useFactory 执行。如果工厂函数中注入了某个外部服务，而这个服务所在的模块没有出现在 imports 中，容器会找不到该依赖，直接报解析错误。
以 TypeORM 多数据库场景为例：
typescript
// app.module.ts — 遗漏 imports
@Module({
imports: [
TypeOrmModule.forRootAsync({
useFactory: (config: ConfigService) => ({
name: 'first',
type: 'postgres',
host: config.get('DB_HOST'),
...
}),
inject: [ConfigService],
// 缺少 imports，ConfigService 无法被解析
}),
],
})
export class AppModule {}这里 inject 中的 ConfigService 需要来自某个模块的导出，但 forRootAsync 如果没有通过额外选项声明 imports，Nest 就没法在工厂执行前找到它。正确写法是补充 imports：
typescript
TypeOrmModule.forRootAsync({
imports: [ConfigModule], // 确保 ConfigService 可用
useFactory: (config: ConfigService) => ({
name: 'first',
type: 'postgres',
host: config.get('DB_HOST'),
...
}),
inject: [ConfigService],
})这样一来，ConfigModule 内导出的 ConfigService 在工厂执行时就已经就绪。
多数据库连接的命名注入
当应用同时连接多个数据库时，每次 forRoot 或 forRootAsync 都必须通过 name 属性为连接命名，后续在仓储注入时用 @InjectRepository 的第二个参数指定连接名称。
typescript
// app.module.ts
@Module({
imports: [
TypeOrmModule.forRoot({
name: 'first',
type: 'postgres',
host: 'localhost',
database: 'primary_db',
entities: [User],
}),
TypeOrmModule.forRoot({
name: 'second',
type: 'postgres',
host: 'localhost',
database: 'analytics_db',
entities: [Log],
}),
],
})
export class AppModule {}在服务中使用对应连接的仓储：
typescript
@Injectable()
export class DataService {
constructor(
@InjectRepository(User, 'first')
private readonly userRepo: Repository<User>,
@InjectRepository(Log, 'second')
private readonly logRepo: Repository<Log>,
) {}
}如果没有指定 name，Nest 会查找默认连接。多个连接中有一个可以不命名（作为默认连接），但其他必须显式命名，否则会冲突。
设计取舍
有限制的地方就存在着取舍。上面的场景可以归结为几个反复出现的决策点。
模块边界与依赖方向。
模块之间的依赖方向应该形成单向无环图。出现环时，forwardRef 只是解决了框架的初始化时序，并没有消除逻辑上的循环。长期来看，将共享代码下沉到一个更基层的模块，是更稳定的做法。这意味着在早期的模块划分中就要留意：如果两个模块将来可能需要互相引用，它们很可能应该共享同一个更底层的依赖。
全局与显式。
全局模块的方便是以牺牲可发现性为代价的。除非是真正的跨应用横切关注点（日志、配置），否则优先用显式导入。显式导入能让你在模块头部一眼看到所有外部依赖，对测试和替换也更友好。
作用域粒度。
默认单例是 Nest 设计的性能基线。请求作用域和瞬态作用域是为那些确实需要随上下文变化的对象提供的，而不是为了“方便拿到请求对象”。在多数场景下，把上下文数据通过参数传递，或者用拦截器/中间件处理横切逻辑，都能避免提升作用域带来的开销。
动态模块的依赖编排。
动态模块的异步配置本质上是声明了一个微小的初始化依赖图。编写 forRootAsync 时，确保 imports 中包含工厂函数需要的所有外部模块，这一点和普通模块的导入规则没有区别。多库场景下，每个连接的配置单元都是独立的，使用命名连接可以防止注入歧义。
这些取舍并不是一成不变的规则，而是在理解框架的限制之后，根据具体项目做出的判断。如果有一个量级较小的内部工具，用几个全局模块和少量 forwardRef 完全可行；但在一个多人维护、业务模块不断增长的项目里，严格一点的边界会让依赖图更容易管理。