如何安装Material UI styles？安装时持续报错怎么办

正确安装流程 #

• 先确认项目前置依赖：本地项目必须已安装react、react-dom，MUI v5版本要求二者版本>=17.0.0，如果使用MUI v4则要求版本>=16.8.0。
• 按使用的包管理器执行对应安装命令：
  • npm：npm install @mui/styles @mui/material @emotion/react @emotion/styled
  • yarn：yarn add @mui/styles @mui/material @emotion/react @emotion/styled
  • pnpm：pnpm add @mui/styles @mui/material @emotion/react @emotion/styled
• 注意：@mui/styles是MUI v5提供的旧版样式兼容包，本身不包含核心组件和样式引擎依赖，必须同步安装@mui/material以及emotion相关依赖，否则会直接报模块缺失错误。如果使用MUI v4版本，不需要单独安装styles包，直接安装@material-ui/core即可，styles能力已经内置在v4核心包中。

报错排查方案 #

• 依赖冲突问题：执行npm ls react（yarn用yarn list react、pnpm用pnpm list react）检查项目内是否存在多版本react副本，MUI要求项目全局只能存在一个react版本，如果检测到多版本，直接删除node_modules文件夹和对应锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行安装命令即可。
• 安装缓存/权限问题：如果安装阶段报EACCES权限错误，不要用sudo强行安装，先修复本地包管理器权限，或者执行npm cache clean --force清理本地安装缓存后重试。
• 模块解析错误：如果安装完成后运行时报Can't resolve '@mui/styles/xxx'类错误，检查是否漏装@mui/material和emotion相关依赖，多数现代脚手架默认不会自动安装peerDependencies，需要手动补全所有要求的依赖项。
• SSR框架适配问题：如果是Next.js、Gatsby这类服务端渲染框架项目，使用@mui/styles需要额外添加服务端样式注入配置，否则会出现hydration不匹配、样式丢失类报错。

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