Angular 17.0.X升级至17.3.3失败：依赖冲突问题

问题背景 #

将Angular应用从17.0.x版本升级到17.3.3，手动更新package.json中的依赖版本后，执行npm install时出现传递依赖冲突错误。

升级前的package.json #

{"name": "ui","version": "0.0.0","scripts": {"ng": "ng","start": "ng serve","build": "ng build","test": "ng test","lint": "ng lint","e2e": "ng e2e"},"private": true,"dependencies": {"@angular/animations": "^17.0.5","@angular/cdk": "^17.0.2","@angular/common": "^17.0.5","@angular/compiler": "^17.0.5","@angular/core": "^17.0.5","@angular/forms": "^17.0.5","@angular/localize": "^17.0.5","@angular/material": "^17.0.2","@angular/material-moment-adapter": "^17.0.2","@angular/platform-browser": "^17.0.5","@angular/platform-browser-dynamic": "^17.0.5","@angular/router": "^17.0.5","@ngx-dropzone/cdk": "^17.1.0","@ngx-dropzone/material": "^17.1.0","chart.js": "^4.2.0","file-saver": "^2.0.5","jwt-decode": "^3.0.0","moment-timezone": "^0.5.33","ng2-charts": "^4.1.1","ngx-mat-select-search": "^7.0.5","ngx-mat-timepicker": "^17.0.1","ol": "^7.4.0","rxjs": "^7.8.1","tslib": "^2.0.0","uuid": "^8.2.0","vis-data": "^7.1.9","vis-timeline": "^7.7.3","vis-util": "^5.0.7","zone.js": "^0.14.2"},"devDependencies": {"@angular-devkit/build-angular": "^17.0.5","@angular/cli": "^17.0.5","@angular/compiler-cli": "^17.0.5","@types/jasmine": "~5.1.4","@types/jasminewd2": "~2.0.13","@types/node": "^20.10.2","codelyzer": "^6.0.2","jasmine-core": "~5.1.1","jasmine-spec-reporter": "~7.0.0","karma": "~6.4.2","karma-chrome-launcher": "~3.2.0","karma-coverage-istanbul-reporter": "~3.0.3","karma-jasmine": "~5.1.0","karma-jasmine-html-reporter": "^2.1.0","protractor": "~7.0.0","ts-node": "~8.3.0","tslint": "~6.1.0","typescript": "5.2.2"}}

升级后的package.json #

{"name": "ui","version": "0.0.0","scripts": {"ng": "ng","start": "ng serve","build": "ng build","test": "ng test","lint": "ng lint","e2e": "ng e2e"},"private": true,"dependencies": {"@angular/animations": "^17.3.3","@angular/cdk": "^17.3.3","@angular/common": "^17.3.3","@angular/compiler": "^17.3.3","@angular/core": "^17.3.3","@angular/forms": "^17.3.3","@angular/localize": "^17.3.3","@angular/material": "^17.3.3","@angular/material-moment-adapter": "^17.3.3","@angular/platform-browser": "^17.3.3","@angular/platform-browser-dynamic": "^17.3.3","@angular/router": "^17.3.3","@ngx-dropzone/cdk": "^17.3.0","@ngx-dropzone/material": "^17.3.0","chart.js": "^4.2.0","file-saver": "^2.0.5","jwt-decode": "^3.0.0","moment-timezone": "^0.5.33","ng2-charts": "^4.1.1","ngx-mat-select-search": "^7.0.5","ngx-mat-timepicker": "^17.1.0","ol": "^7.4.0","rxjs": "^7.8.1","tslib": "^2.0.0","uuid": "^8.2.0","vis-data": "^7.1.9","vis-timeline": "^7.7.3","vis-util": "^5.0.7","zone.js": "^0.14.2"},"devDependencies": {"@angular-devkit/build-angular": "^17.3.3","@angular/cli": "^17.3.3","@angular/compiler-cli": "^17.3.3","@types/jasmine": "~5.1.4","@types/jasminewd2": "~2.0.13","@types/node": "^20.10.2","codelyzer": "^6.0.2","jasmine-core": "~5.1.1","jasmine-spec-reporter": "~7.0.0","karma": "~6.4.2","karma-chrome-launcher": "~3.2.0","karma-coverage-istanbul-reporter": "~3.0.3","karma-jasmine": "~5.1.0","karma-jasmine-html-reporter": "^2.1.0","protractor": "~7.0.0","ts-node": "~8.3.0","tslint": "~6.1.0","typescript": "5.2.2"}}

错误信息（翻译后） #

日志文件：
C:\Users\user\AppData\Local\npm-cache_logs\2024-04-09T17_39_16_916Z-debug-0.log

npm 依赖解析错误报告 #

解析时：ui@0.0.0
已找到：@angular-devkit/build-angular@17.0.6
node_modules/@angular-devkit/build-angular
根项目中声明的开发依赖 @angular-devkit/build-angular@"^17.3.3"

无法解析依赖：
根项目中的开发依赖 @angular-devkit/build-angular@"^17.3.3"

冲突的peer依赖：@angular/compiler@17.3.3
node_modules/@angular/compiler
@angular/localize@17.3.3 需要 peer依赖 @angular/compiler@"17.3.3"
node_modules/@angular/localize
根项目中声明的 @angular/localize@"^17.3.3"
@angular-devkit/build-angular@17.3.3 需要可选peer依赖 @angular/localize@"^17.0.0"
node_modules/@angular-devkit/build-angular
根项目中声明的开发依赖 @angular-devkit/build-angular@"^17.3.3"

修复上游依赖冲突，或使用 --force 或 --legacy-peer-deps 参数重试命令，以接受不正确（可能损坏）的依赖解析。

解决方法 #

1. 使用Angular官方升级工具（推荐） #

手动修改package.json容易遗漏依赖同步，用Angular CLI的升级命令能自动处理所有兼容问题：

ng update @angular/core@17.3.3 @angular/cli@17.3.3

该命令会自动更新所有Angular核心依赖，包括@angular-devkit/build-angular，并自动处理peer依赖的版本匹配。

2. 清理依赖缓存与残留文件 #

如果缓存中残留旧版本依赖导致解析错误，执行以下步骤：

• 删除node_modules文件夹：
  Windows：rmdir /s /q node_modules
  macOS/Linux：rm -rf node_modules
• 删除package-lock.json文件：rm package-lock.json
• 清理npm缓存：npm cache clean --force
• 重新执行npm install

3. 手动检查第三方库兼容性 #

确认项目中第三方库是否支持Angular 17.3.3：

• 例如ngx-mat-select-search@7.0.5，需确认其版本是否兼容Angular 17.3.3，若不兼容则升级到对应版本
• 确保所有Angular生态相关库（如@ngx-dropzone、ngx-mat-timepicker）的版本与Angular核心版本匹配

4. 临时跳过peer依赖检查（不推荐） #

若上述方法无效，可临时使用npm参数强制跳过peer依赖冲突，但可能引入潜在运行时问题：

npm install --legacy-peer-deps

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