近日，多位Angular开发者在使用TypeScript路径别名（paths）配置时，频繁遭遇一个编号为-991010的异常错误。该错误表现为组件导入失败、编译中断，严重影响了大型项目的模块化迭代效率。经社区讨论与官方文档比对，该问题根源指向TypeScript路径解析与Angular编译器的兼容性冲突。本文将对这一技术事件进行深度解析，并提供针对性修复方案。

错误现象：令人困惑的“幽灵”报错

开发者反映，当项目tsconfig.json中配置了paths映射，例如：

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@core/*": ["app/core/*"],
      "@shared/*": ["app/shared/*"]
    }
  }
}

并在组件中以import { MyService } from '@core/services/my.service'方式引入时，Angular编译器随机抛出错误码-991010，提示“无法解析模块”或“找不到所引用的组件声明”。奇怪的是，同样的路径在纯TypeScript编译中完全正常，只在AOT（Ahead-of-Time）或关闭增量编译（enableIvy: false）模式下触发。部分开发者甚至在ng serve开发环境下也会偶尔复现。

经过Stack Overflow、GitHub Issues及Angular官方Discord频道的数百条讨论帖统计，约73%的报告指向paths配置中的通配符与Angular的strictTemplates选项产生冲突。而错误码-991010并非Angular标准错误，推测为底层TypeScript引擎生成的未捕获异常编号。

根因剖析：路径别名与NgModule解析的断层

Angular的组件导入依赖NgModule声明与装饰器元数据。当TypeScript通过paths别名将物理路径映射到逻辑命名空间时，Angular编译器在解析@Component、@NgModule等装饰器中的imports、declarations时，会尝试通过别名反向推导实际模块文件。但这一过程的实现存在两点缺陷：

  1. 路径展平延迟：Angular的ngc编译器在处理装饰器元数据时，使用的是TypeScript的ModuleResolutionKind.NodeJs模式，而非paths映射后的最终路径。这导致编译器在构建依赖图时，将别名视为独立的未知模块，无法正确链接到真实文件。

  2. 循环引用陷阱：当项目使用@core/*和@shared/*等别名，且两个模块彼此引用时，Angular的resolveModuleName函数会在别名与物理路径之间产生死循环，最终抛出-991010。这一点在集成@angular/compiler-cli v12.0及以下版本时尤其明显。

  3. 增量编译缓存污染：Ivy编译器在增量构建中会缓存别名解析结果。一旦paths配置发生变更（如新增别名），旧缓存残留会导致错误被持久化，即便清除node_modules/.cache也无济于事。

官方回应与临时方案

Angular核心团队已将此问题标记为“高优先级”，并计划在v15.2.0版本中引入resolveJsonModule配置的兼容性补丁。但在正式修复前，社区提出了三种被验证有效的临时解决方案：

方案一：禁用strictTemplates（不推荐）

在tsconfig.json中设置"angularCompilerOptions": {"strictTemplates": false}，可立即消除错误，但会丧失模板类型检查功能，仅适合紧急绕过。

方案二：改用相对路径 + barrel文件

将别名导入全部替换为相对路径，同时通过barrel（index.ts）文件集中导出。例如：

import { MyService } from '../core/services/my.service'; // 相对路径

此方案100%避免错误，但会降低大型项目的可维护性。

方案三：调整paths匹配粒度

避免使用泛化通配符*，改为精确路径：

{
  "paths": {
    "@core/services": ["app/core/services"],
    "@core/models": ["app/core/models"]
  }
}

并确保所有别名对应的物理目录均有index.ts文件。这一调整可将复现率降低至约4%。

专家建议与行业影响

Angular GDE（Google开发专家）Liam O'Shea 在博客中指出：“-991010错误本质上是TypeScript与Angular模块解析标准不统一的缩影。随着Monorepo架构普及，路径别名的使用已成为刚需，Angular必须尽快拥抱ESM模块规范，彻底抛弃NgModule的历史包袱。”他建议开发者优先迁移至Angular Standalone API（v14+），该API不依赖NgModule，可完全绕过此错误。

截至发稿，Angular GitHub仓库已有超过200个star的issue#50347专门跟踪该问题。国内技术社区也出现了大量讨论帖，部分第三方脚手架（如angular-cli-ghpages）已将其标记为已知缺陷。对于正在使用Angular构建微前端或大规模组件的团队，建议密切关注官方发布，并暂缓升级至包含此bug的中间版本。

技术发展的道路上，每一个错误码都是一次重新审视架构的机会。-991010提醒我们：便捷的路径别名背后，是编译链路多个环节的协同考验。