Angular 11应用引入自定义库后出现组件未初始化引用错误如何解决？

已复现的报错信息 #

Uncaught ReferenceError: Cannot access 'SomeLibraryComponent' before initialization

问题场景 #

我自行开发了一个Angular库模块（独立工作区），通过package.json的依赖配置将其引入到我的业务应用项目（独立工作区）中，并已在应用的主模块定义中导入了该库模块。
排查堆栈跟踪信息后发现，报错的触发原因是名为SomeParentLibraryComponent的组件尝试初始化其ViewChild属性时出现异常，相关组件代码如下：

@Component({
    selector:'some-parent',
    templateUrl: './some-parent.component.html'
})
export class SomeParentLibraryComponent {
    
    @ViewChild(SomeLibraryComponent, {static: false}) theCauseComponent: SomeLibraryComponent;
    // 其他业务逻辑
}

@Component({
    selector:'some-child',
    templateUrl: './some.component.html'
})
export class SomeLibraryComponent {
    // 其他业务逻辑
}

父组件对应的模板文件内容如下：

<div>
    <!-- 其他模板逻辑 -->
    <some-child></some-child>
    <!-- 其他模板逻辑 -->
</div>

我当前使用的Angular版本为11，业务应用工作区与库工作区均通过angular-cli生成。 #

触发根因 #

这是典型的ES模块循环依赖导致的暂存死区访问错误，和Angular的生命周期配置、ViewChild参数设置没有直接关系：

• 代码执行到SomeParentLibraryComponent的装饰器元数据收集阶段时，需要拿到SomeLibraryComponent的类引用作为@ViewChild的查询条件，但此时代码执行流还没走到SomeLibraryComponent的类定义赋值环节
• 出现这种时序错位的核心原因，是两个组件文件存在交叉导入：比如父组件文件为了拿子组件的类引用做ViewChild查询导入了子组件文件，而子组件文件又因为类型引用、工具函数依赖等场景反向导入了父组件所在的模块或文件，形成了闭环的导入链路
• ESM规范下，所有未完成初始化的类变量都会被放在暂存死区，在赋值前被访问就会直接抛出Cannot access before initialization的ReferenceError
• 很多人会误以为是static: false的配置问题，实际不管静态属性设为true还是false，只要循环依赖存在，在装饰器解析阶段访问未初始化的类引用就会触发报错，和ViewChild的静态配置完全无关

修复方案 #

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

• 首先用循环依赖扫描工具定位问题根节点：在库代码根目录执行npx madge --circular --extensions ts ./，可以直接扫出所有存在交叉导入的文件链路
• 优先从根源拆断循环依赖：
  • 把两个组件共同依赖的类型、工具方法抽离到独立的公共文件，避免两个组件文件互相直接导入
  • 如果是为了ViewChild查询才导入的组件类，可以改用模板引用变量的字符串选择器查询，完全切断对组件类的直接导入依赖：
    1. 父组件模板里给子组件加模板引用：<some-child #someChildRef></some-child>
    2. 父组件代码里把ViewChild的参数从类名改成字符串引用名：@ViewChild('someChildRef') theCauseComponent!: SomeLibraryComponent
    3. 子组件的类型引用要改成仅类型导入：import type { SomeLibraryComponent } from './some-library.component'，这种导入在编译阶段会被完全擦除，不会产生运行时的模块依赖，自然不会触发循环报错
• 如果暂时不想调整业务代码，可以调整库目录下的公共导出文件index.ts的导出顺序：把SomeLibraryComponent的导出放在SomeParentLibraryComponent之前，让模块解析器先完成子组件的类初始化，再去解析依赖它的父组件代码，也能临时绕开报错
• 最后是不推荐长期使用的兜底方案：把ViewChild装饰器里的类参数改成延迟求值的箭头函数，等运行时真正需要查询的时候再去取组件类引用，绕开元数据收集阶段的时序问题，但这种方法没有从根源解决循环依赖，后续代码迭代很容易复现同类报错

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