Angular13库启用Ivy partial编译 组件继承触发NG3003循环错误

问题场景 #

从Angular 11升级到Angular 13开发公共组件库时，按照官方组件库编译要求在tsconfig中添加如下配置：

"enableIvy": true,
"compilationMode": "partial"

配置后编译失败，抛出NG3003错误：

"ChildComponent" Error: One or more import cycles would need to be created to compile this component, which is not supported by the current compiler configuration.

报错的ChildComponent无额外业务逻辑，仅通过类继承关联ParentComponent，代码如下：

export class ChildComponent extends ParentComponent {}

已确认排除以下显式循环场景：

• 父子组件未在彼此的HTML模板中互相引用
• 代码层面无显式双向import引用
• 已尝试依赖注入令牌、接口抽象等通用循环引用解决方案，问题未解决

排查与解决步骤 #

按优先级从高到低操作即可：

• 优先排查桶文件（index.ts）导出导致的隐式循环
  这是纯继承场景触发NG3003的最常见原因，旧版View Engine编译器不会全量扫描桶文件导出内容，因此Angular 11下无异常；partial模式下Ivy编译器收集组件元数据时，会顺着export *的桶导出链加载所有关联模块，只要父组件的导入/导出链路经过同时导出了子组件的桶文件，编译器就会加载子组件，再顺着子组件的继承关系回指父组件，形成隐式循环。
  验证与修复：
  1. 将ChildComponent中引入ParentComponent的路径，从公共桶路径（比如@xxx/lib）改为父组件源码文件的直接相对路径（比如../parent/parent.component）
  2. 检查父组件侧所有导入、导出链路，确保父组件的引用路径不经过同时导出了子组件的桶文件
• 检查组件装饰器参数的引用路径
  如果父组件的@Component装饰器中配置了providers、viewProviders、queries等属性，这些属性里用到的任何值如果是从包含子组件的桶文件引入的，哪怕值本身和子组件完全无关，也会触发编译器全量加载桶文件内容形成循环。
  修复方式：所有装饰器参数中用到的依赖，全部直接引用到对应源码的文件路径，不要走公共桶导出。
• 检查组件装饰器配置遗漏
  确认组件层级的装饰器配置正确：
  1. 如果ChildComponent是对外暴露的可直接使用的组件，必须显式添加@Component装饰器，漏加装饰器时partial模式编译器会回溯父组件元数据，跨导出链回溯时很容易误判循环
  2. 如果ChildComponent是仅用于继承的中间抽象类，不要给它加@Component或@Directive装饰器，直接声明为抽象类即可，避免编译器将其识别为待编译组件做全量元数据扫描
• 次级入口隔离兜底方案
  如果以上操作都未解决问题，先临时将tsconfig中的compilationMode改为full验证编译是否正常：如果full模式可正常编译，即可确认是编译器元数据扫描的隐式循环问题。此时将存在继承关系的组件拆分到独立的ng-packagr次级入口，通过次级入口的天然导出隔离性，切断编译器扫描时的循环路径即可。

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