Angular Material从15.0.3升级到17.0.4后主题定制报错

问题原因 #

Angular Material 16及以上版本切换到了基于Material Design Components (MDC)的底层实现，主题系统的调色板结构发生了重大变化——原15版本中background调色板里的background、card等键名，被替换为符合MDC规范的default、surface、surface-container等新键名，继续使用旧键名会导致mat-color函数无法识别，从而抛出无效CSS值的错误。

解决方案 #

1. 修正颜色取值代码 #

将原来的旧写法：

$background-color: mat-color($_background, background);

替换为对应新键名的写法：

// 获取原15版本中background对应的主背景色
$background-color: mat-color($_background, default);

// 如果是原card颜色，替换为：
$card-color: mat-color($_background, surface);

2. 使用新的主题定义API（推荐） #

Angular Material 17推荐使用mat.define-light-theme/mat.define-dark-theme函数定义主题，替代旧版的mat-light-theme/mat-dark-theme，示例如下：

@use '@angular/material' as mat;

// 定义基础调色板
$primary: mat.define-palette(mat.$indigo-palette);
$accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
$warn: mat.define-palette(mat.$red-palette);

// 定义浅色主题
$light-theme: mat.define-light-theme((
  color: (
    primary: $primary,
    accent: $accent,
    warn: $warn,
  ),
));

// 应用主题到所有组件
@include mat.all-component-themes($light-theme);

3. 更简洁的颜色获取方式 #

使用mat.get-color-from-theme函数直接从主题中提取颜色，无需手动拆解调色板：

// 获取主背景色
$background-color: mat.get-color-from-theme($light-theme, background, default);

// 获取卡片背景色
$card-color: mat.get-color-from-theme($light-theme, background, surface);

验证步骤 #

1. 保存修改后的SCSS文件
2. 重新构建应用（ng build或ng serve）
3. 检查组件样式是否正常渲染，报错是否消失

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