Material UI 与 React 18 的兼容性问题解决指南

版本信息

本文适用于以下版本：

• React 18.x
• Material UI (MUI) v5.x

问题描述

当在 React 18 项目中尝试安装旧版本的 Material UI (v4) 时，会出现依赖冲突错误：

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.3

根本原因

Material UI v4（也称为 @material-ui/core）仅支持 React 16.8+ 和 React 17.x，不支持 React 18。其 peerDependencies 明确指定了兼容的 React 版本：

$ npm view @material-ui/core@4.12.3 peerDependencies
{
  react: '^16.8.0 || ^17.0.0',
  'react-dom': '^16.8.0 || ^17.0.0'
}

解决方案

推荐方案：升级到 MUI v5

MUI v5 (以 @mui/material 命名) 从 5.6.0 版本开始完全支持 React 18。

安装命令

npm

npm install @mui/material @emotion/react @emotion/styled
npm install @mui/icons-material

yarn

yarn add @mui/material @emotion/react @emotion/styled
yarn add @mui/icons-material

导入语句修改

安装新版本后，需要更新导入语句：

// 旧版本导入 (不再适用)
import { makeStyles } from '@material-ui/core/styles';
import Paper from '@material-ui/core/Paper';
import SendIcon from '@material-ui/icons/Send';

// 新版本导入 (使用这些)
import { makeStyles } from '@mui/material/styles';
import Paper from '@mui/material/Paper';
import SendIcon from '@mui/icons-material/Send';

临时解决方案（不推荐）

如果必须使用 Material UI v4，有两种临时方法：

方法一：使用强制安装标志

npm install @material-ui/core --legacy-peer-deps

方法二：降级 React 版本

将 package.json 中的 React 版本降级到 17.x：

{
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}

注意事项

强制安装和降级 React 版本都是临时解决方案，可能存在兼容性风险和安全隐患。建议尽快升级到 MUI v5。

依赖覆盖配置

对于复杂项目，可以在 package.json 中添加覆盖配置：

{
  "dependencies": {
    "@mui/material": "^5.14.13",
    "@mui/icons-material": "^5.14.13",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "overrides": {
    "@mui/styles": {
      "react": ">=18.2.0",
      "react-dom": ">=18.2.0"
    }
  }
}

版本兼容性参考

MUI 版本	React 支持	包名称	状态
v4.x	React 16.8-17.x	@material-ui/core	已弃用
v5.6.0+	React 18.x	@mui/material	推荐使用

总结

React 18 与 Material UI 的兼容性问题源于版本不匹配。最安全、最推荐的解决方案是：

1. 卸载旧版本：npm uninstall @material-ui/core @material-ui/icons
2. 安装新版本：npm install @mui/material @mui/icons-material
3. 更新所有导入语句
4. 检查并更新相关代码以适应 MUI v5 的 API 变化

遵循这些步骤可以确保您的 React 18 项目与 Material UI 完全兼容，同时获得最新的功能和安全更新。