Angular13升级14使用@angular-builders/custom-webpack构建报错

问题现状 #

• 项目完成Angular框架v13到v14版本升级，本地开发依赖、全局Angular CLI版本均锁定为v14.0
• 项目当前使用的@angular-builders/custom-webpack版本为npm源默认latest标签对应的13.1.0版本
• 执行项目构建命令时触发报错，初步排查未发现开发依赖、全局CLI的配置异常
• 初步怀疑报错由@angular-builders/custom-webpack版本适配问题导致：该包官方文档标注13.x版本最高仅支持Angular v13，暂不确定是否需要等待适配v14的正式版本发布

分步排查流程 #

1. 先做依赖版本对齐校验
   执行以下命令拉取本地所有关联构建包的实际安装版本：

   ng version
   npm ls @angular-builders/custom-webpack @angular-devkit/build-angular
   

   构建类Angular生态包有强版本绑定规则：@angular-builders/custom-webpack的大版本必须和本地安装的@angular-devkit/build-angular大版本完全一致，跨大版本使用必然触发构建错误。
2. 做最小场景复现验证
   临时修改angular.json配置，把项目构建器从@angular-builders/custom-webpack:browser换回Angular官方默认的@angular-devkit/build-angular:browser，同时注释掉所有custom-webpack相关的自定义配置，删除node_modules目录、包管理锁文件后重新安装依赖执行构建：
   • 若构建依然报错：问题和@angular-builders/custom-webpack无关，需要排查Angular v14升级带来的其他breaking change，比如第三方组件库适配、废弃API调用、模板严格类型校验问题
   • 若换回默认构建器后构建正常：可100%确认报错由@angular-builders/custom-webpack版本不匹配导致

对应解决方案 #

• 确认是custom-webpack版本适配问题的场景：
  不需要等待正式版发布，该包适配Angular v14的预发布版本已经可用，直接执行命令安装对应大版本即可：

  npm install @angular-builders/custom-webpack@14.0.0-beta.1 -D
  

  安装完成后恢复原有自定义webpack配置，重新执行构建即可解决绝大多数适配类报错。如果预发布版本存在边缘场景bug，可以直接查阅该包的公开问题列表找对应临时补丁，不需要回退整个项目的Angular版本。
• 换回默认构建器依然报错的场景：
  对照Angular官方v13到v14的升级变更清单逐点校验，重点排查三类问题：
  • 模板严格模式下的类型不匹配报错
  • 路由、响应式表单模块中已废弃API的调用
  • 项目依赖的第三方UI组件、工具库是否发布了适配Angular v14的版本
• 兜底方案
  如果预发布版本的custom-webpack无法满足需求，可以直接把自定义webpack配置逻辑迁移到Angular v14官方构建器原生支持的自定义配置能力上，v14版本的官方构建器已经支持直接传入自定义webpack配置，不需要依赖第三方包即可实现等价能力。

提示：所有和Angular构建流程绑定的第三方依赖，都必须和Angular核心包、devkit包保持大版本一致，跨大版本使用没有兼容可能性，不要存在侥幸心理。

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