升级前言：Angular 8 到 13 的迁移记录
项目升级需求要求我们将 Angular 从 8 版本提升至 13 版本，由于无法直接跳级，必须逐级递进。本文详细记录了升级过程中遇到的各类报错信息及其对应的解决方案。
一、升级前的准备工作
首先确保 Node.js 版本不低于 12.20。接着新建一个分支或采用其他方式备份当前项目，以保障安全。最后删除项目目录下的 yarn.lock 或 package-lock.json 文件，避免旧依赖干扰新版本安装。
二、逐级升级的操作步骤
- 升级相关依赖：访问 update.angular.io，根据官方引导将项目逐步升级至 Angular 9～13 对应版本。
- 若单独使用了 @angular/cdk，请执行
ng update @angular/cdk@（对应版本）进行同步更新。 - 升级 NG-ZORRO 组件库：运行
ng update ng-zorro-antd@（对应版本）。 - 升级 NG-ALAIN 框架：执行
ng update ng-alain（对应版本）。
三、常见问题与修复方法
错误1：WARNING in xxx is part of the TypeScript compilation but it's unused.Add only entry points to the 'files' or 'include' properties in your tsconfig.
// 在 exclude 后加上以下信息 "files": ["../src/main.ts", "../src/polyfills.ts"], "include": ["src/**/*.d.ts"]
错误2：Repository is not clean. Please commit or stash any changes before updating.
ng update --all --force --allow-dirty
错误3：Package '@angular/core' is not a dependency…
遇到此类提示，重新安装依赖即可。
npm i
错误4：ERROR in ./src/styles.less (…), @import '~@delon/theme/styles/index'; Can't resolve '@delon/theme/styles/index.less' …
这是由于路径发生了变动，需要移除多余的一层目录。例如 @import '~@delon/theme/styles/index' 中的 styles 层级应去掉。所有报错的目录文件都需要逐一检查修正。
如果路径正确后仍然报错：
那么需要在 angular.json 中配置样式路径：
"stylePreprocessorOptions": {
"includePaths": [
"node_modules/"
]
}
错误5 src/app/layout/default/header/components/taskmange.component.ts:33:28 – error NG1001: @ViewChild options must be an object literal
原因是 @ViewChild 现在要求传入两个参数，而第二个参数缺失。官方说明指出：static 参数决定是否在变更检测运行前解析查询结果。若不提供，编译器将按照默认行为处理。
@ViewChild("taskDrawer", {static: true}) taskDrawer;
// 或者
@ViewChild("taskDrawer", {static: false}) taskDrawer;
// 或者
@ViewChild("taskDrawer") taskDrawer;
请根据实际业务场景选择合适的方式。
错误6：样式丢失
// angular.json 文件引入 "styles": [ "src/styles.less", "./node_modules/ng-zorro-antd/ng-zorro-antd.min.css" ], // styles.less 文件引入 @import '~ng-zorro-antd/ng-zorro-antd.less'; @import '~ng-zorro-antd/style/entry.less'; @import '~ng-zorro-antd/button/style/entry.less';
错误7：ERROR in src/app/core/i18n/i18n.service.ts:13:24 – error TS2307: Cannot find module 'date-fns/locale/en'
import { enUS as dfEn, zhCN as dfZhCn, zhTW as dfZhTw, vi as dfVi } from 'date-fns/locale';
错误8：import { STColumn, STComponent, STReq, STRequestOptions, STRes } from '@delon/abc/table';
// https://github.com/ng-alain/ng-alain/issues/1569 里有说明路径变化，改成下面这样
import { STColumn, STComponent, STReq, STRequestOptions, STRes } from '@delon/abc/st';
错误9：error TS2307: Cannot find module 'date-fns/distance_in_words_to_now'
import formatDistanceToNow from 'date-fns/formatDistanceToNow';
错误10：NullInjectorError: No provider for ACLService!
// 在 app.module.ts 里补上缺失的 provider providers: [ // ... ACLService, AlainConfigService, ],
错误11：Package '@angular/core' is not a dependency…
npm i
错误12：ERROR in Failed to list lazy routes: Unknown module '…/app.module#AppModule'.
（暂无标准修复步骤，建议检查路由配置或版本间兼容性）
错误13：Angular11 升级报错：Two incompatible decorators on class
查阅多种资料未找到通用解法，后来在 Angular 官方文档中发现以下配置可以解决：
{
"angularCompilerOptions": {
"fullTemplateTypeCheck": true,
"strictInjectionParameters": true
}
}
错误14：typescript 不兼容问题 @angular/compiler-cli@8.0.3 requires a peer of typescript@>=3.4 <3.5
npm i typescript@3.4.3
错误15：import { NzMessageService, UploadFile } from 'ng-zorro-antd';
组件导入路径已发生变化：
import { NzMessageService } from 'ng-zorro-antd/message';
import { NzUploadFile } from 'ng-zorro-antd/upload';
错误16：import { NzModalService } from 'ng-zorro-antd';
同样需要更新路径：
import { NzModalService } from 'ng-zorro-antd/modal';
错误17：自定义主题色失效
在 angular.json 中移除已引入的组件主题色，然后在 src/styles.less 中引入预定义主题文件：
@import "../node_modules/ng-zorro-antd/ng-zorro-antd.less"; @import './styles/theme'; @import './styles/index';
错误18：Can't bind to 'formGroup' since it isn't a known property of 'form'
使用 Reactive Forms 需要额外导入 ReactiveFormsModule，详细参考官方文档。
错误19：Angular12 报错 (resize-observer-polyfill) TS2717: Property contentRect must be of type DOMRectReadOnly
提供两种解决办法：
（1）等待第三方库修复更新；
（2）在 tsconfig.json 中添加 "skipLibCheck": true 以跳过第三方库的类型检查。
错误20：
npm install --sa ve-dev raw-loader
错误21：多次注入
platformBrowserDynamic 被重复注入（通常出现在 main.ts 和 app.module.ts 中），删除多余的那一处，例如移除 App.module.ts 中的相关代码。
错误22：angular 从11.x更新到12.x 收到 DON'T USE IT FOR PRODUCTION! 警告
升级到 12.2.17 后，执行以下命令：
ng update @angular/cli --migrate-only --from=11.2.0 --to=12.2.17
再次运行 ng serve，警告即可消除。
错误23：Git无法提交（Must use import to load ES Module）
由于升级需要逐级进行，每一步都需 git commit。临时注释掉 .husky/pre-commit 中以 npx 开头的行，完成全部升级后再恢复。
错误24：An unhandled exception occurred: Directory import '…/dev-server' is not supported resolving ES modules
这是版本不兼容导致，需要升级 @angular-devkit/build-angular：
// 升级前 "@angular-devkit/build-angular": "~12.2.18" // 升级后 "@angular-devkit/build-angular": "~13.3.9"
错误25：export 'startWith' (imported as 'startWith') was not found in 'rxjs'
原因是 rxjs 版本过低，需要升级：
// 升级前 "rxjs": "~6.5.3" // 升级后 "rxjs": "~7.5.0"
错误26：Module '"@delon/chart"' has no exported member 'G2TimelineData'
路径已变更，需要调整：
import { G2TimelineData } from '@delon/chart/timeline';
错误27：编译后git出现了很多缓存编译文件
更新 .gitignore，添加以下忽略项：
# Compiled output /dist /tmp /out-tsc /bazel-out # Node /node_modules npm-debug.log yarn-error.log # IDEs and editors .idea/ .project .classpath .c9/ *.launch .settings/ *.sublime-workspace # Visual Studio Code .vscode/* !.vscode/settings.json !.vscode/tasks.json !.vscode/launch.json !.vscode/extensions.json .history/* # Miscellaneous /.angular/cache .sass-cache/ /connect.lock /coverage /libpeerconnection.log testem.log /typings # System files .DS_Store Thumbs.db
错误28：抽屉组件内部自定义内容无法展示
自定义的 ng-content 外层需要使用
错误29：antd-Table组件渲染数据时出现第一行空白行
添加 [nzScroll]="{ x: '1500px' }" 后出现了空白行，解决方案如下：
:host ::ng-deep .ant-table-measure-now {
visibility: collapse;
}
30.报错如下：
在 tsconfig.json 中新增 "skipLibCheck": true 即可。
升级总结
以上便是从 Angular 8 升级至 Angular 13 过程中遇到的主要问题以及对应的解决办法。版本跨度较大，坑点众多，但只要按步骤推进、逐一排查，终究能顺利完成迁移。希望这份实战记录能为遇到类似需求的开发者提供参考。
