Angular NG0200 循环依赖错误完全解析：从报错原理到代码级排查与修复

面向检索的摘要

NG0200 是 Angular 依赖注入（DI）在检测到“循环依赖”（Circular Dependency in DI）时抛出的运行时错误代码。本文以 Angular 官方错误文档 [NG0200.md](https://gitcode.com/GitHub_Trending/an/angular/blob/f44bf0fe221288d03107cc78acfbe333a9a9b7b5/adev/src/content/reference/errors/NG0200.md?utm_source=gitcode_repo_files) 为主体骨架，结合本仓库 `@angular/core` 的注入器实现源码（[r3_injector.ts](https://gitcode.com/GitHub_Trending/an/angular/blob/f44bf0fe221288d03107cc78acfbe333a9a9b7b5/packages/core/src/di/r3_injector.ts?utm_source=gitcode_repo_files)、[errors_di.ts](https://gitcode.com/GitHub_Trending/an/angular/blob/f44bf0fe221288d03107cc78acfbe333a9a9b7b5/packages/core/src/render3/errors_di.ts?utm_source=gitcode_repo_files)）与大量真实测试用例，讲清 NG0200 的完整含义、触发机制、错误消息中 `Source` 与 `Path` 字段的解读方法、逐行排查调用栈的思路，以及移除依赖、重构为单向依赖、`forwardRef`、`Injector` 延迟注入、可选注入等修复与规避方案，并对比 NG0200 与 NG2001 等关联错误的边界。

什么是 NG0200？

NG0200 是 Angular 依赖注入在运行时识别到**循环依赖（循环依赖，Circular Dependency）**后抛出的诊断错误代码，其官方文档即本仓库中的 NG0200.md。完整错误形式通常形如：

NG0200: Circular dependency detected for `UserService`.
Path: UserService -> EmployeeService -> UserService.

在 Angular 源码中，该错误码对应 RuntimeErrorCode.CYCLIC_DI_DEPENDENCY = -200（见 packages/core/src/errors.ts）。负值编码用于区分 Angular 自有错误与来自浏览器、RxJS 等外部异常，-200 这一恒定的枚举值在消息中的可读名称就是 NG0200。

所谓“循环依赖”，官方定义是：当某个服务的依赖（无论直接还是间接）最终反过来依赖该服务自身时，循环就形成了。例如若 UserService 依赖 EmployeeService，而 EmployeeService 又依赖 UserService，那么 Angular 为了创建 UserService 必须先实例化 EmployeeService，而实例化 EmployeeService 又需要 UserService——这一先有鸡还是先有蛋的递归在运行时是无法终止的，Angular 必须在此刻抛出 NG0200，而不是陷入无限递归导致栈溢出。

值得注意的是，NG0200 是一种运行时 DI 错误，它与 TypeScript 编译期的“import 环”或打包工具（如 Rollup、webpack）报告的“循环模块依赖”属于不同层面：即便两个服务不处于同一模块文件，只要在同一注入器解析链上形成递归，运行时就会命中 NG0200。

循环依赖是如何被检测出来的：注入器内部的“三态标记”

要理解 NG0200 的排查方向，最好先弄清楚 Angular 是如何“发现”循环的。从源码看，Angular 在 R3Injector 中为每个 token 记录维护了一个状态机，其实现位于 r3_injector.ts，核心是 Record 的三个状态：

/**
 * Marker which indicates that a value has not yet been created from the factory function.
 */
const NOT_YET = {};

/**
 * Marker which indicates that the factory function for a token is in the process of being called.
 * ...
 * a circular dependency among the providers.
 */
const CIRCULAR = {};

结合 hydrate() 方法的实际逻辑（r3_injector.ts），可以概括出如下检测流程：

1. 注入器首次请求某个 token 时，其记录值处于 NOT_YET（尚未创建）状态；
2. Angular 在真正调用工厂函数之前，先把记录标记为 CIRCULAR（正在创建中），再执行工厂；
3. 如果在创建 A 的过程中，其依赖链上再次请求到同一个 token A（即递归回到原点），此时 A 的记录仍停留在 CIRCULAR，hydrate() 命中该状态并立即抛出循环依赖错误：

if (record.value === CIRCULAR) {
  throw cyclicDependencyError(ngDevMode ? stringify(token) : '');
}

也就是说，Angular 并不做静态的依赖图分析，而是通过“创建中即递归回访”这一朴素的运行时标记来判定循环。这带来两点重要推论，可写入你的排查直觉：

• 只有实际被实例化的依赖链才会触发 NG0200。没有被注入、没有被解析的“纸面依赖”不会报错；
• 该错误只在开发模式（ngDevMode）下携带完整消息。生产构建中 ngDevMode 为假，错误消息为 NG0200（无文本详情的 RuntimeError），源码中的写法是 cyclicDependencyError(ngDevMode ? stringify(token) : '')。因此 NG0200 的详细排查信息要在开发服务器或 ng test 环境下查看。

错误消息中 Source 与 Path 的含义：一次真实的“寻环”过程

开发模式下，Angular 在抛出 NG0200 前会沿着调用栈向上逐步拼接完整的依赖路径。相关机制位于 r3_injector.ts：每当错误向上冒泡经过一层注入器，当前 token 会被“前插”（prependTokenToDependencyPath）进错误对象携带的 NG_TOKEN_PATH，直到没有上层注入器时，再通过 augmentRuntimeError 将路径格式化进最终消息（实现见 errors_di.ts）。

最终消息的格式函数说明了两类附加字段（见 errors_di.ts）：

function formatErrorMessage(text, code, path = [], source = null) {
  let pathDetails = '';
  // 若路径为空或仅含一个元素（自身），不附加额外信息
  if (path && path.length > 1) {
    pathDetails = ` Path: ${path.join(' -> ')}.`;
  }
  const sourceDetails = source ? ` Source: ${source}.` : '';
  return formatRuntimeError(code, `${text}${sourceDetails}${pathDetails}`);
}

据此，一条典型的 NG0200 消息由四部分组成，仓库测试 di_spec.ts 断言了它的精确形态：

NG0200: Circular dependency detected for `InjectionToken A`.
Source: DynamicTestModule.
Path: InjectionToken A -> InjectionToken B -> InjectionToken A.
Find more at https://angular.dev/errors/NG0200

逐一解读：

• **Circular dependency detected for \X`**：X` 是被识别为“回到原点”的那个 token，即整个循环在创建到它时被发现；
• Source: ...：从哪个注入器（如某个 NgModule、DynamicTestModule、平台注入器等）发起了解析，便于你定位“是哪一棵注入树里的循环”；
• Path: A -> B -> A.：Angular 用 -> 串联出完整的递归解析路径，这是定位断点最重要的信息，路径两端的同名 token 就是循环的闭合点；
• Find more at .../NG0200：formatRuntimeError 自动追加的官方文档链接，对应的拼装逻辑见 errors.ts。

注意：只有当路径长度大于 1 时消息才会附加 Path，若循环是“自身注入自身”（长度为 1 或为空），则不会有路径段。一个真实的“自身循环”示例如下：

@Injectable()
export class ServiceA {
  constructor(private b: ServiceB) {}
}

@Injectable()
export class ServiceB {
  constructor(private a: ServiceA) {}  // NG0200: A -> B -> A
}

哪些场景会触发 NG0200：结合测试用例盘点

本仓库的测试覆盖了多种会命中 NG0200 的真实形态，逐一对照可以帮你识别自己的代码属于哪种：

1. 服务间通过构造器相互注入

这是最经典的形态，di_spec.ts 用两个互相依赖的 InjectionToken 展示了这一点：MyComp 注入 A，A 的实现类 ServiceA 又注入 B，ServiceB 反过来注入 A，于是在 TestBed.createComponent(MyComp) 时抛出 NG0200。

2. 指令 / 组件之间相互注入

Angular 允许指令与组件通过构造函数互相注入彼此，形成环同样报错。di_forward_ref_spec.ts 中 DirectiveA 与 DirectiveB 同时出现在模板 <div dirA dirB></div> 上并相互注入，TestBed.createComponent(MyComp) 时抛出：

NG0200: Circular dependency detected for `DirectiveA`.
Path: DirectiveA -> DirectiveB -> DirectiveA.

注意该用例为了绕过 TypeScript 的“使用前声明”限制，对 DirectiveA 使用了 @Inject(forwardRef(() => DirectiveA))——这恰好说明 forwardRef 只解决“源码书写顺序/引用声明”问题，无法解决运行时 DI 环。

3. 通过 inject() 函数在属性初始化期注入

Angular 14+ 的 inject() 可在类字段初始化时使用，这种写法同样会被检测。di_spec.ts 用 a = inject(A) / b = inject(B) 复现了环，说明无论你用构造器注入还是函数式注入，底层的 hydrate/CIRCULAR 判定是一致的。

4. 通过 Injector.get() 手动解析形成环

即使不通过构造器，只要在工厂执行期间同步调用 Injector.get() 递归回访同一 token 也会命中 NG0200（见 di_spec.ts 起的用例）。这表明“循环”的本质是同步解析时序上的递归回访，与注入的书写方式无关。

5. NgModule 提供链（Module/Environment 注入器层级）

循环可以跨越多层注入器（Module 注入器与 Environment 注入器）。测试中 Source: DynamicTestModule 表明解析发起于测试模块注入器。Angular 会在每层注入器把当前 token 前插到路径中（见 r3_injector.ts 对 previousInjector 的逐级冒泡处理），因此跨层循环也能看到完整 Path。

如何排查 NG0200：三步定位法

官方文档 NG0200.md 给出的排查指引可以展开为以下可操作步骤：

第 1 步：利用调用栈（Call Stack）定位环的起点

NG0200 抛出的时刻，就是解析链第一次“回访自身”的时刻。在浏览器 DevTools 的 Call Stack 面板中，从 cyclicDependencyError（源码见 errors_di.ts）向下回溯 hydrate、get 等帧，每一层帧对应的 token 共同构成环。配合错误消息中的 Path: A -> B -> A.，即可直接锁定循环闭合点的两个 token。

第 2 步：画出依赖关系图，找出闭环

官方建议把组件、模块或服务的依赖关系“映射出来”（原文：mapping out the component, module, or service's dependencies），找出导致问题的环。实践中可以：

1. 打开错误消息 Path 字段，记下循环链条上每个 token；
2. 在 IDE 中分别检索这些类的构造函数、字段初始化 inject()、以及 @NgModule.providers / providers 数组中对彼此的引用；
3. 用箭头画出 A → B → A（或更长的 A → B → C → A），箭头所指即依赖方向，闭环即是病灶。

第 3 步：打破环

修复的总体思路官方表述为：“打破这个环（circle）即可解决错误，最常见的方式是移除或重构依赖，使它们不再互相依赖。”根据环的具体成因，可以选择下文四种修复方案之一。

修复方案一：移除或重构为单向依赖（最推荐）

这是官方首推、也最彻底的方案：让依赖方向变为单向的树状结构，消除闭环。仍以 UserService / EmployeeService 为例，需要判断二者中谁真正“属于”谁，或抽取出公共依赖：

// 重构前：双向依赖 → NG0200
@Injectable()
export class UserService {
  constructor(private employeeService: EmployeeService) {}
}
@Injectable()
export class EmployeeService {
  constructor(private userService: UserService) {} // 反向依赖造成环
}

// 重构后：抽取出共用的 ReportingService，打破环
@Injectable()
export class ReportingService { /* 公共逻辑迁移至此 */ }

@Injectable()
export class UserService {
  constructor(private reporting: ReportingService) {}
}
@Injectable()
export class EmployeeService {
  constructor(private reporting: ReportingService) {}
}

当两个服务在业务上确实“谁也离不开谁”时，往往意味着存在职责重叠——把重叠部分下沉为第三个服务，或让其中一方改为通过事件、状态管理（如 Angular signals）间接通信，是从根上消除 NG0200 的长期方案。

修复方案二：改用 forwardRef（仅解决“声明顺序”类问题）

forwardRef 的源码与文档均在本仓库中（forward_ref.ts）。它提供“惰性引用”，让类可以在其定义之前被另一个类引用，例如用于组件/指令在模板里互相引用、或类 A 引用尚未声明的类 B：

@Directive({selector: '[dirA]', standalone: false})
class DirectiveA {
  constructor(@Inject(forwardRef(() => DirectiveB)) sibling: DirectiveB) {}
}

@Directive({selector: '[dirB]', standalone: false})
class DirectiveB {
  constructor(sibling: DirectiveA) {}
}

但在修复 NG0200 时请务必清醒：

• 该示例在运行时仍然会抛出 NG0200（测试断言见 di_forward_ref_spec.ts）；
• 正如 forward_ref.ts 注释所述，forwardRef 也用于“打破 standalone 组件 import 的循环引用”，但它解决的是 TypeScript 声明顺序 / 模块加载层面的环，resolveForwardRef 最终返回的仍是同一个真实类；
• 若你的 NG0200 仅源于两个类因文件书写顺序而无法直接互相 import（编译错误），forwardRef 是正确工具；若环在运行时确实存在（双方都在构造期同步解析对方），forwardRef 无效，必须采用方案一或方案三。

修复方案三：通过 Injector 实现延迟注入

当 A、B 的环无法轻易拆开，而 B 对 A 的依赖并不发生在构造器执行期间（例如只在某个方法被调用时才需要 A）时，可以让 B 持有 Injector，在真正需要时再手动 get：

import {Injector, Injectable} from '@angular/core';

@Injectable()
export class UserService {
  constructor(private employeeService: EmployeeService) {}
}

@Injectable()
export class EmployeeService {
  private userService: UserService | null = null;
  // 注入 Injector 自身不会触发循环：它不依赖 A/B
  constructor(private injector: Injector) {}

  doSomethingWithUser() {
    // 延迟到方法调用时解析 A，绕开构造期递归
    if (!this.userService) {
      this.userService = this.injector.get(UserService);
    }
    return this.userService;
  }
}

其原理与源码一致：CIRCULAR 判定只发生在 token 的工厂正在执行期间（r3_injector.ts）。当 EmployeeService 已经创建完成后，再通过 injector.get(UserService) 发起解析，此时 UserService 的记录不再处于 CIRCULAR 状态，环被时序上“错开”了。这一手法的适用前提是：循环中至少有一方对另一方的依赖必须是惰性的（不在构造期使用），否则仍会报错。

修复方案四：@Optional() 或 @Host() 等限定符改变解析路径（有限场景）

有时循环的发生是因为某一方在错误的注入器层级上重复解析了同一 token。@Optional()、@Self()、@SkipSelf()、@Host() 这些参数装饰器会改变 DI 的向上查找行为（对应的查找逻辑见 r3_injector.ts 中基于 flags 对 parent/NullInjector 的选择）。例如让子级依赖改为从更上层的注入器（@SkipSelf()）获取同一 token，或允许缺省（@Optional() 配 null 兜底），可能在特定层级结构中切断递归回访。

但需要明确其局限：如果环是纯粹的逻辑双向依赖（A 与 B 在同一层级内互注），这些限定符并不改变 A、B 之间的递归事实，无法根治问题。因此它属于“结构调整”类手段，应配合对注入层级（可参考本仓库 DI 指南 hierarchical-dependency-injection.md）的理解使用，而非万能药。

NG0200 与相近错误的边界

排查时容易将 NG0200 与其他 DI 错误混淆，这里做一个快速区分：

错误码	含义	一句话区分
NG0200	循环依赖：解析链在创建期回访自身	消息含 Circular dependency detected 与 Path
NG0201	找不到 provider	消息含 No provider for ... found，对应 throwProviderNotFoundError（errors_di.ts）
NG0203	在非注入上下文中调用 inject()	与注入顺序、执行上下文有关

从源码可以看出两者在错误传播路径上的相似性：r3_injector.ts 的 get() 捕获环节同时处理 CYCLIC_DI_DEPENDENCY 与 PROVIDER_NOT_FOUND 两类错误码并逐级拼接路径（r3_injector.ts）。因此若某依赖在解析中先“找不到”又表现为环，常说明 provider 注册结构与注入层级需要一并审查；对注入层级与 provider 作用域的深入理解可继续阅读 hierarchical-dependency-injection.md、di-in-action.md 与本仓库 DI 系列指南的其余页面（guide/di）。

小结：NG0200 排查清单

1. 先确认消息形态：开发模式下应看到 Source 与 Path，据此锁定发起注入器与循环闭合点；生产模式无详细文本，请切回开发模式复现。
2. 画依赖图找闭环：把 Path 中每个 token 的构造器与 inject() 依赖画出，找到环形链。
3. 按需选修复手段：能拆则拆（单向依赖）；只是声明顺序问题用 forwardRef；依赖确为惰性则用 Injector 延迟解析；涉及注入器层级错位时考虑 @Optional()/@SkipSelf() 等限定符。
4. 回归验证：修复后用测试框架断言不再抛出以 NG0200: 开头的错误，仓库相关测试（如 di_spec.ts）是很好的参考样板。