Vite环境下Material-UI主题上下文无法共享至类库问题

场景还原 #

根组件中通过以下方式提供MUI主题：

<ThemeProvider theme={theme}>
    <MuiPickersUtilsProvider utils={MomentUTCUtils}>
        <Router history={history}>
            <>
                <CssBaseline />
                <App />
            </>
        </Router>
    </MuiPickersUtilsProvider>
</ThemeProvider>

在App中渲染一个来自第三方node包的组件，该组件通过以下代码访问主题上下文：

const variantColors = new Map<ToastVariant, string>([
    [ToastVariant.Common, theme.palette.primary.main],
    [ToastVariant.Error, theme.palette.common.Error.fill],
    [ToastVariant.Info, theme.palette.common.Warning.fill],
    [ToastVariant.Success, theme.palette.common.Success.fill],
])

此时抛出错误：

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'fill')

该场景在Webpack环境下可正常运行，且第三方包已编译为ESM格式导入。

排查与解决 #

1. 检查主题结构一致性 #

错误提示theme.palette.common.Error为undefined，先确认传入ThemeProvider的theme对象是否匹配组件依赖的结构：

• 核对自定义主题定义，是否存在键名大小写差异（比如主题里写error，组件里用Error）
• 确认主题中palette.common下的Error、Warning、Success属性是否已正确赋值，没有遗漏

2. 解决MUI多实例冲突 #

如果业务项目和第三方包分别安装了独立的MUI依赖，会导致ThemeProvider的上下文实例不共享，第三方包读取的是自身依赖的空上下文：

• 将第三方包的MUI相关依赖（@mui/material、@mui/styles等）从dependencies移到peerDependencies，强制使用宿主项目的MUI版本
• 执行npm dedupe或yarn dedupe消除重复依赖

3. 验证模块导入与编译配置 #

确认第三方包的ESM编译是否符合要求：

• 检查第三方包package.json的module字段，确认指向的文件正确导出组件
• 确保第三方包导入MUI的useTheme钩子时使用正确路径（比如import { useTheme } from '@mui/material/styles'）

4. 确认组件上下文范围 #

在第三方组件中临时打印theme对象，验证它是否处于ThemeProvider的包裹范围内：

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

const ThirdPartyComponent = () => {
    const theme = useTheme();
    console.log('当前主题:', theme); // 查看theme是否为undefined或结构缺失
    // ... 原有代码
}

如果theme为undefined，排查路由或组件嵌套是否导致组件跳出了ThemeProvider的范围。

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