Angular10.1.6升级11时@ng-select依赖不兼容致迁移失败

问题场景 #

执行升级命令ng update @angular/core@11 @angular/cli@11将项目从Angular ~10.1.6升级至11版本时抛出peer依赖不兼容报错，报错核心信息如下：

Package "@ng-select/ng-select" has an incompatible peer dependency to "@angular/common" (requires ">=9.0.0 <10.0.0" (extended), would install "11.2.14").
Package "@ng-select/ng-select" has an incompatible peer dependency to "@angular/core" (requires ">=9.0.0 <10.0.0" (extended), would install "11.2.14").
Package "@ng-select/ng-select" has an incompatible peer dependency to "@angular/forms" (requires ">=9.0.0 <10.0.0" (extended), would install "11.2.14").
✖ Migration failed: Incompatible peer dependencies found.
Peer dependency warnings when installing dependencies means that those dependencies might not work correctly together.
You can use the '--force' option to ignore incompatible peer dependencies and instead address these warnings later.
  See "/tmp/ng-qLRhlg/angular-errors.log" for further details.

当前运行环境版本信息：

Angular CLI: 14.0.1
Node: 16.15.1
Package Manager: npm 8.11.0 
OS: linux x64

@angular-devkit/architect    0.1400.1 (cli-only)
@angular-devkit/core         14.0.1 (cli-only)
@angular-devkit/schematics   14.0.1 (cli-only)
@schematics/angular          14.0.1 (cli-only)

添加--force参数强制完成升级后，无法正常安装项目依赖。

根因判定 #

该问题与Node.js、npm版本无关，核心触发原因有两点：

• 全局安装的Angular CLI版本为14.0.1，跨3个大版本执行v11的升级迁移任务，版本匹配逻辑、迁移脚本执行均存在已知兼容问题
• 项目内安装的@ng-select/ng-select版本仅支持Angular 9.x范围，和Angular 11存在明确的peer依赖冲突，--force参数仅跳过升级时的版本校验，不会自动处理依赖兼容问题，不兼容的版本写入package.json后必然导致后续依赖安装失败

修复步骤 #

1. 对齐全局Angular CLI版本
   卸载当前高版本全局CLI，安装与目标升级版本匹配的v11系列CLI，避免跨版本执行升级的兼容问题：

npm uninstall -g @angular/cli
npm install -g @angular/cli@11

执行完成后运行ng version，确认全局CLI版本为11.x后再进行后续操作。
2. 提前升级兼容Angular 11的第三方依赖
@ng-select/ng-select@7.x是官方适配Angular 11的版本，先进入项目目录执行命令升级该依赖，从根源解决peer冲突：

npm install @ng-select/ng-select@7 --save

3. 执行正式升级
   此时依赖冲突已经提前解决，无需加--force参数，直接执行升级命令即可：

ng update @angular/core@11 @angular/cli@11

4. 依赖异常兜底处理
   如果升级完成后仍存在依赖安装失败问题，删除本地依赖缓存和锁文件后重新安装即可：

rm -rf node_modules package-lock.json
npm install

注意事项 #

• Angular跨大版本升级需遵循逐版本升级规则，且全局Angular CLI版本需尽量和目标升级版本保持同大版本，避免高版本CLI运行低版本迁移脚本导致的不可预期错误
• 升级Angular框架版本前，需提前核对所有第三方Angular生态依赖的版本兼容范围，先升级适配目标Angular版本的第三方依赖，再执行框架升级，不要依赖--force参数跳过版本校验，跳过校验产生的版本不兼容问题都会在后续安装或运行阶段暴露

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