React项目如何从material-ui迁移至mui，或实现二者共存

报错原因 #

旧版 Material UI（v4 及更早版本）包名规则为@material-ui/*，v5 版本重构后正式更名为 MUI，包名规则改为@mui/*，二者样式方案、导出规则、依赖结构完全不兼容。你之前安装的@material-ui/core@next属于 v5 的测试版本，和正式版@mui/material导出重叠，会进一步引发冲突。

方案一：两个版本共存 #

• 先清理错误安装的依赖：
  yarn remove @mui/material @material-ui/core@next
• 安装两个版本的稳定正式包：

# 安装旧版 Material UI v4 最终稳定版
yarn add @material-ui/core@4.12.4
# 安装新版 MUI v5 正式版及依赖
yarn add @mui/material @emotion/react @emotion/styled @mui/styles

• 配置根组件避免类名冲突：

import { StyledEngineProvider, ThemeProvider, createTheme } from '@mui/material/styles';
import { ThemeProvider as OldThemeProvider, createMuiTheme } from '@material-ui/core/styles';

const mui5Theme = createTheme();
const mui4Theme = createMuiTheme();

function App() {
  return (
    {/* 配置MUI v5样式优先注入，避免和旧版类名冲突 */}
    <StyledEngineProvider injectFirst>
      <ThemeProvider theme={mui5Theme}>
        <OldThemeProvider theme={mui4Theme}>
          {/* 原有项目代码 */}
        </OldThemeProvider>
      </ThemeProvider>
    </StyledEngineProvider>
  );
}

• 日常使用时区分导入路径即可：旧组件从@material-ui/core导入，新组件从@mui/material导入。

方案二：全量迁移到 MUI v5（推荐） #

该方案适合长期维护项目，避免后续版本迭代的兼容问题：

• 卸载所有旧版 Material UI 依赖：
  yarn remove @material-ui/core @material-ui/icons @material-ui/styles
  （如果有其他@material-ui/开头的依赖，也一并卸载）
• 安装新版 MUI v5 全套依赖：
  yarn add @mui/material @emotion/react @emotion/styled @mui/icons-material
• 全局替换项目中的导入路径：
  • 所有import {} from '@material-ui/core'替换为import {} from '@mui/material'
  • 所有import {} from '@material-ui/icons'替换为import {} from '@mui/icons-material'
• 按控制台报错调整更名API即可，常见更名项：
  • createMuiTheme更名为createTheme
  • makeStyles迁移至@mui/styles包下导入，或改用styled组件写法

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