Material UI v7 升级实战：从 JavaScript 颜色操作迁移到 CSS Native Color

本文是 Material UI 升级 v7 过程中"启用 native color（原生颜色）"这一迁移项的完整指南。native color 是一个可选（opt-in）特性：启用后，Material UI 会用 CSS 的 color-mix() 与 relative colors（相对颜色）取代过去由 JavaScript 完成的颜色计算。读完本篇，你将知道如何开启该特性、如何在开发者工具中验证生效、为什么继续调用 alpha / lighten / darken 会破坏应用、如何用 theme.alpha() 等主题颜色函数替代它们，以及如何借助官方 codemod 批量完成迁移。

前提条件：升级到 Material UI v7.3.0 及以上

native color 从 v7.3.0 开始提供，升级前请先将 @mui/material 更新到最新版本（至少 v7.3.0）：

# npm
npm install @mui/material

# pnpm
pnpm add @mui/material

# yarn
yarn add @mui/material

需要特别说明的是浏览器兼容性问题：relative colors 与 color-mix() 属于较新的 CSS 能力，官方文档中明确提示该特性只在现代浏览器中生效。如果你的用户群体中仍存在旧浏览器，请在启用前确认浏览器支持情况，这也是该特性默认关闭（nativeColor 默认值为 false）的原因之一。

启用 native color

在 createTheme() 中把 cssVariables.nativeColor 设置为 true：

const theme = createTheme({
  cssVariables: { nativeColor: true },
});

启用之后，Material UI 生成的样式会改用 CSS color-mix() 与相对颜色来推导派生色（如 light、dark、半透明色等），而不是在构建主题时于 JavaScript 侧计算并写死 hex/rgba 值。

验证方式：打开浏览器开发者工具，在 Elements 面板的 Styles 区域搜索 color-mix。如果生效，你会看到 Material UI 的颜色 token 以 CSS 变量形式出现，派生值由 color-mix() 现场计算得出。

源码视角：nativeColor 在主题构建中做了什么

在 createThemeWithVars.js 中可以看到该选项的处理逻辑：

• nativeColor 从 options 中解构，默认值为 false，因此不显式开启时行为与旧版完全一致（见 packages/mui-material/src/styles/createThemeWithVars.js#L134）；
• 一旦开启，主题会切换颜色空间并改用 CSS 变量引用：源码中注释解释了选择 oklch 的原因——"it is the most perceptually uniform color space and widely supported"（见 packages/mui-material/src/styles/createThemeWithVars.js#L170-L174）；
• 在生成各组件样式时，大量派生色值从静态 hex 变为 getCssVar('palette-xxx') 形式的 CSS 变量引用，例如 palette.error.light、palette.primary.main 等位置都会按 nativeColor 开关在"JS 计算值"与"CSS 变量"之间切换；部分无法直接取变量的场景则通过 colorMix() / safeAlpha() 等工具生成 color-mix(...) 表达式；
• 该开关还会级联影响对比色变量的生成：源码末尾有 enableContrastVars: nativeColor（见 packages/mui-material/src/styles/createThemeWithVars.js#L972），即 native color 模式下 contrastText 等 token 也会变成 CSS 变量，这正是下一节"JavaScript 颜色操作会失效"的根源。

处理 JavaScript 颜色操作：为什么 alpha() 会坏

如果你在自己的代码里用 @mui/* 导出的 alpha、lighten、darken 函数去操作已经改为 native color 的颜色值，应用可能直接报错。原因是这些函数内部按 hex/rgb 格式解析颜色字符串，而 native color 模式下取到的颜色是 CSS 变量或相对颜色表达式，JavaScript 无法解析。

典型坏例子——操作 contrastText token：

import { alpha } from '@mui/material/styles';

const theme = createTheme({
  cssVariables: { nativeColor: true },
});

// ❌ 这会出错，因为 `alpha` 不支持 relative colors
console.log(alpha(theme.palette.primary.contrastText, 0.3));

正确做法是改用主题颜色函数 theme.alpha()：

const theme = createTheme({
  cssVariables: { nativeColor: true },
});

// ✅ 可以正常工作，因为 `theme.alpha` 支持 relative colors
console.log(theme.alpha(theme.palette.primary.contrastText, 0.3));

theme.alpha() 这类适配器函数感知 CSS 变量上下文：当传入的值是 CSS 变量/相对颜色时，它会生成可在浏览器中求值的 color-mix() 表达式，而不是尝试在 Node/构建期把颜色字符串解析成数字通道。lighten 和 darken 同理，都应替换为对应的 theme.lighten() / theme.darken() 主题函数。

theme.alpha() 等主题颜色函数在 v7 是独立于 native color 的另一项变更（详见 v7 升级总览）。未启用 native color 时也可以安全使用它们；启用后则必须使用它们，否则对 *Channel 或 contrast token 的旧式操作会失效。

移除对 channel token（*Channel）的依赖

开启 native color 后，不要再依赖任何 *Channel token（如 palette.primary.mainChannel）。旧模式下这些 token 的值被保证是"空格分隔的数字通道"（例如 25 118 210），方便你手工拼 rgba(...)；但在 native color 模式下，它们不再保证是这种纯通道形式（值可能就是 CSS 变量），手工拼接会得到无效 CSS。

替代方案是用主题颜色函数完成同样的事情：

- `rgba(${theme.vars.palette.primary.mainChannel} / 0.3)`
+ `theme.alpha((theme.vars || theme).palette.primary.main, 0.3)`

这里 (theme.vars || theme) 是兼容写法：开启 CSS 变量模式时从 theme.vars 读取，未开启时回退到 theme 本体，因此同一段样式在两种模式下都可用。

使用官方 codemod 批量迁移

Material UI 提供了 codemod，把来自 @mui/system/colorManipulator 或 @mui/material/styles 的 alpha()、lighten()、darken() 调用替换为主题颜色函数：

npx @mui/codemod@latest v7.0.0/theme-color-functions <path>

变换效果示例：

- import { alpha } from '@mui/system/colorManipulator';
- // or import { alpha } from '@mui/material/styles';

 styled('div')(({ theme }) => ({
   width: '100%',
   height: '100%',
   '&.good': {
-    backgroundColor: theme.vars
-      ? `rgba(${theme.vars.palette.success.mainChannel} /  0.3)`
-      : alpha(theme.palette.success.main, 0.3),
+    backgroundColor: theme.alpha((theme.vars || theme).palette.success.main, 0.3),
   },
   '&.bad': {
-    backgroundColor: theme.vars
-      ? `rgba(${theme.vars.palette.error.mainChannel} /  0.3)`
-      : alpha(theme.palette.error.main, 0.3),
+    backgroundColor: theme.alpha((theme.vars || theme).palette.error.main, 0.3),
   },
 }));

从 codemod 源码 theme-color-functions.js 可以确认其识别范围与行为边界：

• 它扫描的导入来源包括 @mui/system/colorManipulator、@mui/material/styles 以及 @mui/material 三个位置；文件中若没有导入 alpha / lighten / darken 三者中的任何一个，会直接跳过不做任何变换；
• .d.ts 类型声明文件被显式排除（直接原样返回），避免误改类型定义；
• 对形如 theme.vars ? ... : alpha(...) 的三元条件表达式，它会重写为基于 (theme.vars || theme) 的单一表达式，把"CSS 变量模式 / 非 CSS 变量模式"双分支合并为主题颜色函数的统一写法——这与上一节手工给出的 (theme.vars || theme) 模式一致。

相关行为还有配套测试用例，位于 theme-color-functions.test.js 及同目录下的 test-cases/，可以在仓库中直接查看变换前后对照。

升级检查清单

结合本篇内容，迁移到 native color 的完整步骤可以归纳为：

1. 将 @mui/material 升级到最新版（≥ v7.3.0），并确认目标浏览器支持 color-mix() 与 relative colors；
2. 在 createTheme() 中设置 cssVariables: { nativeColor: true }；
3. 打开开发者工具搜索 color-mix，确认颜色 token 已以 CSS 变量 + 原生颜色函数的形式输出；
4. 运行 codemod npx @mui/codemod@latest v7.0.0/theme-color-functions <path> 批量替换 alpha / lighten / darken 调用为主题颜色函数；
5. 手动排查并移除所有 *Channel token 的拼接用法（如 rgba(${...mainChannel} / 0.3)），改用 theme.alpha() 等主题颜色函数；
6. 回归测试涉及透明色、对比文字（contrastText）派生色的组件，重点覆盖深色模式切换场景。

完成以上步骤后，你的应用颜色派生逻辑就完全交给 CSS 原生能力处理：不再需要 JavaScript 侧的颜色运算，也天然支持 oklch、oklab、display-p3 等现代颜色空间，以及把 palette 直接指向外部 CSS 变量的颜色别名场景（更多用法可参考 native color 文档）。