无法升级至Angular Material v17：项目使用legacy组件，需转用新组件

一、排查项目中的Legacy组件依赖 #

先定位所有使用Legacy组件的地方：

• 搜索代码中导入路径包含@angular/material/legacy-*的模块，比如MatLegacyButtonModule、MatLegacyCardModule
• 检查模板文件，查找带有mat-legacy-前缀的指令/组件，比如<mat-legacy-button>、<mat-legacy-form-field>
• 查看package.json，确认是否存在@angular/material-experimental等包含Legacy组件的依赖包

二、批量替换Legacy组件为MDC-based新组件 #

1. 自动迁移（推荐）

使用Angular CLI的官方迁移工具自动处理大部分替换：

ng generate @angular/material:mdc-migration

该命令会自动替换模块导入、模板指令，并提示需要手动调整的复杂场景。

2. 手动替换（针对自动迁移未覆盖的场景）

按组件类型逐一替换：

• 按钮/表单字段：MatLegacyButtonModule → MatButtonModule；模板中<mat-legacy-button> → <mat-button>；MatLegacyFormFieldModule → MatFormFieldModule；<mat-legacy-form-field> → <mat-form-field>
• 卡片/对话框：MatLegacyCardModule → MatCardModule；<mat-legacy-card> → <mat-card>；MatLegacyDialogModule → MatDialogModule
• 表格/分页器：MatLegacyTableModule → MatTableModule；<mat-legacy-table> → <mat-table>；MatLegacyPaginatorModule → MatPaginatorModule
• 其他组件（如菜单、日期选择器等）遵循同样规则，移除legacy-前缀，对应模块和组件名去掉Legacy

三、清理Legacy相关配置与依赖 #

• 删除package.json中不再需要的Legacy依赖（如@angular/material-experimental的Legacy子包），运行npm install更新依赖
• 检查angular.json中的样式配置，确保未引入Legacy主题文件（新主题路径与旧版一致，如@angular/material/prebuilt-themes/indigo-pink.css，无需修改，只需移除legacy-theme相关引用）

四、分步升级Angular与Material版本 #

由于从Angular 13直接跳至18跨度较大，建议分阶段升级以降低冲突：

1. 先将Angular升级至16版本，对应安装Angular Material 16：

   ng update @angular/core@16 @angular/cli@16 @angular/material@16
   

2. 升级至Angular 17，同步安装Angular Material 17：

   ng update @angular/core@17 @angular/cli@17 @angular/material@17
   

3. 最后升级至Angular 18及对应Material版本：

   ng update @angular/core@18 @angular/cli@18 @angular/material@18
   

五、修复编译与运行时错误 #

替换完成后，处理可能出现的细节问题：

• 部分组件的输入/输出属性有变更，比如mat-select的panelClass用法不变，但某些Legacy组件的disabled状态逻辑可能调整，需对照官方文档修正
• 样式适配：新组件的CSS类名可能与Legacy版本略有差异，检查页面样式是否正常，必要时调整自定义CSS

六、验证功能完整性 #

• 运行ng build --prod确认无编译错误
• 执行ng test确保单元测试通过
• 手动测试所有交互组件（对话框、表单、菜单等），验证样式与功能符合预期

内容的提问来源于stack exchange，提问作者חיים בו סימון