Angular 12 NX monorepo 构建异常 TS路径映射配置问题求解

• 优先核对根目录tsconfig.base.json的paths配置，NX 项目的全局路径映射必须统一在该文件定义，禁止在 app、lib 各自的 tsconfig 中重复定义 @libA/@libB 相关映射，标准配置参考：

  {
    "compilerOptions": {
      "paths": {
        "@your-org/libA": ["libs/libA/src/index.ts"],
        "@your-org/libB": ["libs/libB/src/index.ts"]
      }
    }
  }
  

• 检查所有子目录（app1、libA、libB）的 tsconfig 的 extends 字段，确认是否正确指向根目录的tsconfig.base.json，不要出现多余的paths配置覆盖全局规则。
• 核对 lib 的公共导出规范：libA、libB 的src/index.ts（公共 API 文件）必须显式导出所有外部需要用到的组件、枚举、接口，禁止 app 或其他 lib 直接引用 lib 内部的深层路径（例如@your-org/libB/src/lib/components/xxx.ts），所有外部引用必须走公共 API，避免 ng-packagr 打包后内部路径变化导致引用失效。
• 检查 app1 的tsconfig.app.json的include/exclude字段，不要误排除 lib 源码路径或者全局类型路径，也不要添加多余的 include 规则覆盖全局配置。
• 确认 VSCode 使用的是项目本地的 TypeScript 版本：打开任意 ts 文件，点击编辑器右下角的 TS 版本号，选择「使用工作区版本」，避免版本差异导致路径识别异常。

• 核对每个 lib 根目录的ng-package.json配置，确认lib.entryFile字段正确指向src/index.ts，没有路径写错的问题。
• 检查 lib 对应的package.json依赖声明：libB 作为公共依赖库，要把自身的公共依赖准确写到dependencies或peerDependencies中；libA 的package.json要把 libB 加到peerDependencies里，不要把 libB 打包到 libA 的产物中，避免重复打包冲突。
• 如果你手动修改了 lib 构建产物的输出路径，要同步更新tsconfig.base.json的paths配置和 lib 的构建配置，保持路径匹配；默认 NX 会自动处理可构建库的路径映射，不需要手动改 dist 目录的映射。

• 检查根目录nx.json的 target 依赖配置，确认已经开启了依赖项预构建规则，参考配置：

  {
    "targetDefaults": {
      "build": {
        "dependsOn": ["^build"]
      }
    }
  }
  

  该配置会自动让所有项目的 build 目标先执行其依赖项的 build 目标，避免构建 app1 时使用未编译的 lib 源码或者旧的构建产物。
• 可以手动按顺序执行nx build libB && nx build libA && nx build app1验证，如果手动按顺序构建成功，基本可以确定是依赖顺序配置异常导致的问题。

• 先判断报错类型：如果是「找不到模块@xxx/xxx」类报错，优先排查路径映射和公共导出配置；如果是「类型不兼容」「xxx不是已知元素」类报错，检查对应 lib 的模块是否正确导出了组件/指令，app 对应模块是否正确导入了 lib 的模块、是否遗漏了CommonModule等公共依赖。
• 执行构建时添加--verbose参数输出完整编译日志：nx build app1 --verbose，查看编译器解析路径时实际查找的文件路径，定位路径解析错误的具体原因。
• 清理 NX 缓存后重试：执行nx reset清理所有本地构建缓存，排除缓存异常导致的奇怪报错。

内容的提问来源于stack exchange，提问作者GS-Scooter