Angular构建NGCC失败报Cannot read property 'text' of undefined是什么原因

该错误本质是Angular的Ivy兼容编译器ngcc在处理UMD格式第三方依赖包时，无法正确解析依赖的导入语句，触发了TypeScript语法解析层的报错，以下是常见触发原因和对应解决方案：

常见触发原因 #

• node_modules依赖损坏，存在下载不完整或者缓存异常的包
• TypeScript版本与当前Angular版本不兼容，导致语法解析逻辑不匹配
• 第三方依赖包的UMD格式不符合ngcc解析规则，常见于版本过旧、未适配当前Angular版本的npm包
• ngcc本地缓存存在脏数据，重复触发解析错误

解决方案 #

1. 清理依赖缓存重装 #

先删除项目根目录下的node_modules文件夹、package-lock.json/yarn.lock/pnpm-lock.yaml锁文件，再执行对应包管理工具的安装命令：

# npm用户
npm install
# yarn用户
yarn install
# pnpm用户
pnpm install

重装完成后尝试重新构建。

2. 校验Angular与TypeScript版本匹配 #

确认当前项目Angular大版本对应的兼容TypeScript版本范围，参考匹配规则：

• Angular 14 支持 TypeScript 4.6~4.8
• Angular 15 支持 TypeScript 4.8~4.9
• Angular 16 支持 TypeScript 4.9~5.1
• 更高版本对应关系可直接查看Angular官方版本说明
  如果版本不匹配，调整package.json中TypeScript的版本到兼容范围后，重新执行依赖安装。

3. 定位并处理异常依赖包 #

在package.json的scripts字段中添加调试命令：

"ngcc:debug": "ngcc --debug"

执行npm run ngcc:debug，查看执行日志中报错前最后处理的依赖包，即为触发异常的包：

• 优先将该依赖包升级到适配当前Angular版本的最新稳定版
• 如果是未维护的冷门依赖包，可在项目根目录的tsconfig.json中添加ngcc跳过配置：

  {
    "angularCompilerOptions": {
      "ngccSkipLibs": ["异常依赖包名"]
    }
  }
  

4. 手动预执行ngcc编译 #

执行以下命令手动触发ngcc全量编译所有依赖：

npx ngcc --properties es2020 browser module main

等执行完成后再运行项目构建命令。

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