Angular11 ng serve启动报Cannot read property 'add' of undefined错误求助

问题根因 #

报错触发位置为@ngtools/webpack Ivy编译插件初始化逻辑，本质是依赖版本不兼容导致Webpack编译钩子API调用失败：

• 错误堆栈指向node_modules/@ngtools/webpack/src/ivy/plugin.js:170，该行逻辑是向Webpack编译钩子集合注册回调，因为找不到对应钩子对象，调用.add()方法时直接抛出类型错误
• 依赖配置存在明显冲突：项目使用的@angular-devkit/build-angular@~0.1102.4是Angular 11配套构建工具，内置绑定Webpack 4.x版本，但devDependencies中手动声明了webpack@^5.70.0，安装依赖时顶层Webpack会被替换为5.x版本，和Angular 11构建插件的API完全不兼容
• Angular生态包版本未对齐：@angular/cli版本为11.2.2，其余@angular/*核心包版本为11.2.14，小版本偏差也可能放大兼容问题

解决步骤 #

• 移除手动安装的不兼容Webpack依赖
  执行命令卸载手动安装的Webpack：

  npm uninstall webpack
  

  注意：Angular 11及更早版本的构建工具已经封装了匹配版本的Webpack，不需要手动在项目中安装Webpack依赖，手动安装的版本不匹配必然触发编译异常。

• 对齐Angular全生态依赖版本
  编辑package.json，将所有Angular官方相关包版本统一对齐到11.2.14，对应配置片段参考：

  "devDependencies": {
    "@angular-devkit/build-angular": "~0.1102.14",
    "@angular/cli": "^11.2.14",
    "@angular/common": "^11.2.14",
    "@angular/compiler": "^11.2.14",
    "@angular/compiler-cli": "^11.2.14",
    "@angular/core": "^11.2.14",
    "@angular/forms": "^11.2.14",
    "@angular/platform-browser": "^11.2.14",
    "@angular/platform-browser-dynamic": "^11.2.14",
    "@angular/router": "^11.2.14",
    "@babel/runtime": "^7.13.10",
    "@babel/runtime-corejs3": "^7.17.2",
    "@ngx-translate/core": "^13.0.0",
    "@ngx-translate/http-loader": "^6.0.0",
    "@types/glob": "^7.2.0",
    "@types/jasmine": "^3.10.3",
    "@types/node": "^14.14.22",
    "@types/systemjs": "^6.1.1",
    "@webcomponents/webcomponentsjs": "^2.5.0",
    "core-js": "^3.21.1",
    "glob": "^7.2.0",
    "jasmine-core": "^4.0.1",
    "jasmine-spec-reporter": "^7.0.0",
    "karma": "^6.3.17",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage": "^2.2.0",
    "karma-jasmine": "^4.0.1",
    "karma-jasmine-html-reporter": "^1.7.0",
    "karma-junit-reporter": "^2.0.1",
    "karma-sonarqube-unit-reporter": "~0.0.23",
    "ng-packagr": "^11.2.0",
    "node-fetch": "2.6.1",
    "node-localstorage": "^2.1.6",
    "puppeteer": "^13.5.0",
    "rxjs": "^6.6.0",
    "ts-node": "^10.7.0",
    "tslib": "^2.3.1",
    "typescript": "~4.1.5",
    "zone.js": "~0.11.5"
  }
  

• 清理缓存重装依赖
  依次执行命令，彻底清除旧依赖残留：

  # Windows系统执行以下命令删除旧依赖和锁文件
  rd /s /q node_modules
  del package-lock.json
  # 如果你使用yarn作为包管理工具，额外执行 del yarn.lock
  
  # 重新安装依赖
  npm install
  

• 对齐全局Angular CLI版本
  执行ng v查看全局安装的CLI版本，如果不是11.x分支，执行以下命令安装匹配版本：

  npm install -g @angular/cli@11.2.14
  

  避免全局CLI和项目本地构建包API不匹配触发异常。

• 验证启动
  上述操作完成后，重新执行ng serve启动项目即可。

兜底排查 #

如果操作完仍报错，可按以下方向检查：

• 确认项目没有自定义Webpack配置：比如是否使用了@angular-builders/custom-webpack之类的自定义构建工具，额外引入的Webpack配置是否兼容Webpack 4
• 查看临时错误日志C:\Users\XXX588\AppData\Local\Temp\ng-uEZQDG\angular-errors.log的完整输出，确认是否有单文件语法错误、第三方库编译异常等前置报错
• 确认Node.js版本符合要求：Angular 11兼容的Node.js版本范围是10.13.x/12.11.x/14.x，不要使用16及以上高版本Node运行Angular 11项目

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