Angular 12类库启用Ivy partial编译模式出现NG3003循环依赖错误

Ivy partial编译模式针对类库做了更严格的检查，模板中直接使用其他组件时必须显式导入对应组件类型，跨文件的双向导入会触发NG3003报错。普通应用的JIT/AOT编译允许这类循环是因为编译阶段会做循环依赖的自动消解，类库的partial编译为了保证产物的通用性没有做这类处理。

方案1：使用动态组件渲染解耦（推荐，适合大规模项目） #

改造核心是让两个互相依赖的组件不再直接导入对方，而是通过公共的动态渲染层加载组件，彻底打破跨文件依赖循环：

1. 新增独立的公共文件定义组件映射和接口

// ui-item.model.ts
export interface UiItemLike {
  type: 'Container' | 'TabContainer' | 'Button';
  uiItems?: UiItemLike[];
}

// ui-component.token.ts
import { InjectionToken, Type } from '@angular/core';
import { UiItemLike } from './ui-item.model';

export const UI_COMPONENT_MAP = new InjectionToken<Record<string, Type<unknown>>>('UI_COMPONENT_MAP');

2. 新增通用动态渲染组件，所有组件的渲染都通过这个组件完成

// ui-item-renderer.component.ts
import { Component, Input, Inject, ViewContainerRef, ComponentRef } from '@angular/core';
import { UI_COMPONENT_MAP } from './ui-component.token';
import { UiItemLike } from './ui-item.model';

@Component({
  selector: 'ui-item-renderer',
  template: ``
})
export class UiItemRendererComponent {
  @Input() item: UiItemLike;
  private componentRef: ComponentRef<unknown>;

  constructor(
    private viewContainerRef: ViewContainerRef,
    @Inject(UI_COMPONENT_MAP) private componentMap: Record<string, Type<unknown>>
  ) {}

  ngOnChanges() {
    this.viewContainerRef.clear();
    const componentType = this.componentMap[this.item.type];
    if (!componentType) return;
    this.componentRef = this.viewContainerRef.createComponent(componentType);
    (this.componentRef.instance as {uiItems?: UiItemLike[]}).uiItems = this.item.uiItems;
  }
}

3. 在NgModule中注册所有组件和映射

// ui.module.ts
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { UI_COMPONENT_MAP } from './ui-component.token';
import { ContainerComponent } from './container.component';
import { TabContainerComponent } from './tab-container.component';
import { ButtonComponent } from './button.component';
import { UiItemRendererComponent } from './ui-item-renderer.component';

@NgModule({
  imports: [CommonModule],
  declarations: [
    ContainerComponent,
    TabContainerComponent,
    ButtonComponent,
    UiItemRendererComponent
  ],
  exports: [
    ContainerComponent,
    TabContainerComponent,
    UiItemRendererComponent
  ],
  providers: [
    {
      provide: UI_COMPONENT_MAP,
      useValue: {
        Container: ContainerComponent,
        TabContainer: TabContainerComponent,
        Button: ButtonComponent
      }
    }
  ]
})
export class UiModule {}

4. 修改原有组件模板，移除直接依赖对方的选择器，改用渲染组件

// container.component.ts 模板部分
template: `
  <h2>Container</h2>
  <ng-container *ngFor="let item of uiItems">
    <ui-item-renderer [item]="item"></ui-item-renderer>
  </ng-container>
`,

// tab-container.component.ts 模板部分
template: `
  <h2>TabContainer</h2>
  <div>
    <h3>Fake tab 1</h3>
    <ui-item-renderer [item]="{type: 'Container', uiItems: uiItems.uiItems}"></ui-item-renderer>
  </div>
  <div>
    <h3>Fake tab 2</h3>
  </div>
`,

改造后两个组件都只依赖公共的模型和渲染组件，不再互相导入，完全消解循环依赖，后续新增组件只要注册到映射表即可，不用修改现有渲染逻辑。

方案2：合并相互依赖的组件到同一文件（改造成本最低，适合小型场景） #

NG3003的循环是跨文件导入导致的，将互相依赖的ContainerComponent和TabContainerComponent放到同一个ts文件中，不需要改业务代码即可直接解决问题：

// container-and-tab.component.ts
import { Component, Input, OnInit } from '@angular/core';
import { UiItemLike } from '../ui-item-like';

@Component({
  selector: 'my-container',
  template: `
    <!-- 原有模板代码不变 -->
  `
})
export class ContainerComponent implements OnInit, UiItemLike {
  // 原有逻辑不变
}

@Component({
  selector: 'my-tab-container',
  template: `
    <!-- 原有模板代码不变 -->
  `
})
export class TabContainerComponent implements OnInit, UiItemLike {
  // 原有逻辑不变
}

该方案无需改动业务逻辑，仅调整文件结构即可解决问题，缺点是组件代码耦合在同一个文件，不适合组件逻辑复杂、代码量较大的场景。

方案3：使用ngComponentOutlet简化动态渲染 #

如果使用Angular 14及以上版本，可以用内置的ngComponentOutlet指令省去自定义渲染组件的步骤，改造更简洁：

1. 新增公共服务存储组件映射

// ui-component.service.ts
import { Injectable, Type } from '@angular/core';
import { UiItemLike } from './ui-item.model';
// 注意此处只导入类型，使用 import type 避免运行时依赖
import type { ContainerComponent } from './container.component';
import type { TabContainerComponent } from './tab-container.component';

@Injectable({ providedIn: 'root' })
export class UiComponentService {
  private componentMap: Record<string, Type<unknown>> = {};

  registerComponent(type: string, component: Type<unknown>) {
    this.componentMap[type] = component;
  }

  getComponent(type: string) {
    return this.componentMap[type];
  }
}

2. 在两个组件的构造函数中注册自身

// container.component.ts
export class ContainerComponent {
  constructor(uiComponentService: UiComponentService) {
    uiComponentService.registerComponent('Container', ContainerComponent);
  }
}

// tab-container.component.ts
export class TabContainerComponent {
  constructor(uiComponentService: UiComponentService) {
    uiComponentService.registerComponent('TabContainer', TabContainerComponent);
  }
}

3. 模板中使用ngComponentOutlet渲染

// container.component.ts 模板部分
template: `
  <h2>Container</h2>
  <ng-container *ngFor="let item of uiItems">
    <ng-container *ngComponentOutlet="uiComponentService.getComponent(item.type); inputs: {uiItems: item.uiItems}"></ng-container>
  </ng-container>
`,

内容的提问来源于stack exchange，提问作者staxx6