升级Angular11配套@angular/material时出现_applyBodyHighContrastModeCssClasses未定义报错

核心根因 #

• 版本不匹配：仅升级@angular/cli、@angular/material、@angular/cdk到11.2.4，但@angular/core、@angular/common等Angular核心依赖仍为更低的11.x子版本，导致Material内部依赖的注入对象缺失。
• 模块导入顺序错误：@angular/material的_applyBodyHighContrastModeCssClasses方法依赖BrowserModule初始化的Platform、DomAdapter服务，若在BrowserModule之前导入Material相关模块，或重复调用forRoot()导入核心Material模块，会导致注入对象为undefined。
• SSR环境兼容问题：若项目启用了服务端渲染（SSR），浏览器专属的Material服务在服务端初始化时会因缺失DOM对象触发该报错。

可行排查与修复步骤 #

1. 统一所有@angular生态的依赖版本
   所有@angular开头的包必须严格对齐到11.2.4版本，禁止仅升级Material、CDK、CLI包。package.json中需配置如下：

   "dependencies": {
     "@angular/animations": "~11.2.4",
     "@angular/common": "~11.2.4",
     "@angular/compiler": "~11.2.4",
     "@angular/core": "~11.2.4",
     "@angular/forms": "~11.2.4",
     "@angular/platform-browser": "~11.2.4",
     "@angular/platform-browser-dynamic": "~11.2.4",
     "@angular/router": "~11.2.4",
     "@angular/cdk": "~11.2.4",
     "@angular/material": "~11.2.4"
   },
   "devDependencies": {
     "@angular/cli": "~11.2.4",
     "@angular/compiler-cli": "~11.2.4"
   }
   

2. 修正根模块导入顺序
   必须保证BrowserModule为根模块第一个导入的依赖，后续再导入动画模块、Material相关模块，禁止在BrowserModule之前导入任何Material相关内容。正确的导入顺序示例：

   // src/app/app.module.ts
   import { BrowserModule } from '@angular/platform-browser';
   import { NgModule } from '@angular/core';
   import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
   import { AppRoutingModule } from './app-routing.module';
   import { AppComponent } from './app.component';
   import { MatIconModule } from '@angular/material/icon';
   
   @NgModule({
     declarations: [AppComponent],
     imports: [
       BrowserModule,
       BrowserAnimationsModule,
       AppRoutingModule,
       MatIconModule // Material模块放在所有核心平台模块之后导入
     ],
     bootstrap: [AppComponent]
   })
   export class AppModule { }
   

   若存在共享模块重复调用forRoot()导入Material核心模块的情况，需移除非根模块中的forRoot()调用，仅在根模块执行一次核心模块的根导入。
3. 清理依赖缓存后重装
   不要仅删除package.json重装，需同步删除依赖目录与锁文件，避免旧版本缓存残留：

   # 删除依赖目录与版本锁文件
   rm -rf node_modules package-lock.json
   # 重新安装依赖
   npm install
   

4. SSR环境额外处理
   若项目启用SSR，需将浏览器专属的Material模块拆分，服务端模块替换为对应的Noop实现，禁止在服务端初始化依赖DOM的Material服务。

注：该报错为Angular 11升级到11.2.x小版本时的高频问题，90%以上的案例由版本不匹配或导入顺序错误导致。

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