无法向@mui/system的styled()方法传递自定义主题该如何解决？

算力阿峰

2026-9-25

问题根因

你遇到的运行时主题属性缺失问题，是两个常见错误共同导致的：

类型声明扩展了错误包的主题接口：你当前扩展的@mui/styles是MUI v5已废弃的legacy样式方案，你使用的@mui/system的styled方法读取的是自身/@mui/material的主题定义，两者不互通
运行时主题生成/Provider导入错误：要么没有用官方的createTheme方法合并默认配置与自定义配置，要么使用了从@mui/styles导入的废弃ThemeProvider，导致自定义配置没有正确注入

解决方案

1. 修正类型声明

删除你现有的针对@mui/styles/defaultTheme的扩展代码，换成对应包的类型扩展：
如果你的项目依赖@mui/material，使用如下声明：

import "@mui/material/styles";

declare module "@mui/material/styles" {
  // 扩展Palette接口新增你自定义的属性
  interface Palette {
    yourCustomAttr: string;
  }
  interface PaletteOptions {
    yourCustomAttr?: string;
  }
  // 如果是全局扩展主题根属性，扩展Theme接口即可
  interface Theme {
    customGlobalField: number;
  }
}

如果是单独使用@mui/system没有依赖@mui/material，则替换为扩展@mui/system的对应接口即可。

2. 修正运行时配置

必须使用createTheme方法生成主题对象，不要直接传入自定义对象，该方法会自动合并默认主题配置与你的自定义配置：

import { createTheme } from "@mui/material/styles";

const theme = createTheme({
  palette: {
    // 你的自定义palette属性，会和默认palette合并
    yourCustomAttr: "#123456"
  }
});

确认ThemeProvider的导入来源正确，不能从@mui/styles导入：

// 正确导入路径，依赖@mui/material的场景
import { ThemeProvider, StyledEngineProvider } from "@mui/material/styles";
// 单独使用@mui/system的场景
// import { ThemeProvider } from "@mui/system";