Material UI 安装完全指南：依赖安装、styled-components 替换、Roboto 字体与 CDN 快速上手

本篇指南基于 Material UI（MUI）仓库官方安装文档展开，覆盖组件库的完整安装流程：默认安装命令与 React 版本兼容要求、React 18 及以下项目的 react-is 版本冲突解决方案、styled-components 替换默认 Emotion 引擎的完整配置、Roboto 字体与 Material Icons 图标的两种接入方式，以及基于 CDN 的免构建快速体验方案。读完后你可以将 Material UI 正确集成进任意 React 项目，并理解仓库源码层面各依赖项的真实约束。

默认安装

Material UI 当前版本为 v9（以 packages/mui-material/package.json 中的 9.4.0 为准），使用 Emotion 作为默认样式引擎。将以下三个包加入你的项目即可：

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

pnpm add @mui/material @emotion/react @emotion/styled

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

这三个包的角色分别是：

• @mui/material：组件库本体，提供 Button、Table、Dialog 等全部 Material Design 组件；
• @emotion/react：Emotion 的核心运行时，提供 styled、css 等 API；
• @emotion/styled：Emotion 的 styled 工厂函数。

Peer dependencies 与 React 版本约束

react 和 react-dom 是 peer dependencies，必须在安装 Material UI 之前就已存在于项目中。官方文档给出的 peer 版本范围为：

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
  "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
}

这一点在源码中可以得到印证。查看 packages/mui-material/package.json，@mui/material 声明的 peerDependencies 为：

"peerDependencies": {
  "@emotion/react": "^11.5.0",
  "@emotion/styled": "^11.3.0",
  "@types/react": "^17.0.0 || ^18.0.0 || ^19.0.0",
  "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
  "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
},
"peerDependenciesMeta": {
  "@emotion/react": { "optional": true },
  "@emotion/styled": { "optional": true }
}

可以注意到两个细节：Emotion 两个包被标记为 optional peer dependency——这是因为当你选择 styled-components 方案时，它们可以不存在；@types/react 同样为可选，仅供 TypeScript 项目使用。

React 18 及以下项目的 react-is 版本对齐

如果你使用的是 React 18 或更早版本，需要将 react-is 锁定到与你 React 主版本一致的版本。以 react@18.3.1 为例，分两步操作：

第一步：安装对应版本的 react-is

npm install react-is@18.3.1

pnpm add react-is@18.3.1

yarn add react-is@18.3.1

第二步：在 package.json 中配置 resolutions / overrides，强制统一依赖树中的版本

// npm
{
  …
  "overrides": {
    "react-is": "^18.3.1"
  }
}

// pnpm
{
  …
  "overrides": {
    "react-is": "^18.3.1"
  }
}

// yarn
{
  …
  "resolutions": {
    "react-is": "^18.3.1"
  }
}

为什么需要这一步？

Material UI 自身依赖 react-is@19（见 packages/mui-material/package.json 中的 "react-is": "^19.2.8"），而 react-is@19 改变了 React 元素的识别方式。如果你的项目运行在 React 18 或更早版本，依赖树中出现两个不匹配的 react-is 版本会导致 prop 类型检查在运行时报错。

从源码结构看，这一依赖被多个核心组件直接使用——例如 Accordion.js、Tabs.js、SelectInput.js 等组件文件都从 react-is 导入 isValidElement 用于子元素校验。因此强制 react-is 与你的 React 版本对齐，是避免运行时错误的必要手段。React 19 项目则无需此步骤，直接安装即可。

使用 styled-components 替换 Emotion

Material UI 默认使用 Emotion 作为样式引擎。如果项目中已全面采用 styled-components，可以通过官方适配包切换。

安装

npm install @mui/material @mui/styled-engine-sc styled-components

pnpm add @mui/material @mui/styled-engine-sc styled-components

yarn add @mui/material @mui/styled-engine-sc styled-components

其中 @mui/styled-engine-sc 是官方的 styled-components 适配层。查看 packages/mui-styled-engine-sc/package.json，它对 styled-components 的 peer 要求为 ^6.0.0。官方 styled-components 集成指南 明确建议：styled-engine-sc 的主版本应与 Material UI 保持一致（例如 v9 的 @mui/material 搭配 v9 的 @mui/styled-engine-sc）。

Bundler 配置：替换默认引擎

安装适配包还不够，还需要在打包层面让 @mui/material 内部引用的 @mui/styled-engine 指向 @mui/styled-engine-sc：

yarn（通过 resolutions）：

 {
   "dependencies": {
-    "@mui/styled-engine": "latest"
+    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
   },
+  "resolutions": {
+    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
+  },
 }

npm（webpack alias + tsconfig paths）：

 module.exports = {
   //...
+  resolve: {
+    alias: {
+      '@mui/styled-engine': '@mui/styled-engine-sc'
+    },
+  },
 };

 {
   "compilerOptions": {
+    "paths": {
+      "@mui/styled-engine": ["./node_modules/@mui/styled-engine-sc"]
+    }
   },
 }

Next.js：

+const withTM = require('next-transpile-modules')([
+  '@mui/material',
+  '@mui/system',
+  '@mui/icons-material', // 如果使用了 @mui/icons-material
+]);
+
+module.exports = withTM({
   webpack: (config) => {
     config.resolve.alias = {
       ...config.resolve.alias,
+      '@mui/styled-engine': '@mui/styled-engine-sc',
     };
     return config;
   }
+});

重要限制：SSR 项目请慎用 styled-components

自 2021 年末起，styled-components 不兼容服务端渲染的 Material UI 项目。原因是 babel-plugin-styled-components 无法处理 @mui 包内部的 styled() 工具函数，会导致服务端与客户端样式不一致。官方在 styled-components 集成指南 与安装文档中均强烈建议 SSR 项目使用 Emotion。

Roboto 字体配置

Material UI 的默认排版体系使用 Roboto 字体。从源码测试用例可以确认这一默认值：createTheme.test.js 中 @mui/system 的主题默认 fontFamily 为 "Roboto", "Helvetica", "Arial", sans-serif；而 prepareTypographyVars.test.ts 展示了默认排版各字重的取值——h1/h2 为 300、body1/body2/caption 为 400、button/h6 为 500。这正是官方文档要求加载 300/400/500/700 四个字重的原因。

方案一：Fontsource（推荐）

npm install @fontsource/roboto

pnpm add @fontsource/roboto

yarn add @fontsource/roboto

在入口文件中按需导入：

import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';

Fontsource 支持按需加载特定字重、斜体和字符子集，Material UI 默认排版仅依赖 300、400、500、700 四个字重，这样加载即可满足默认主题。

方案二：Google Web Fonts CDN

在项目的 <head /> 标签内添加：

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
/>

仓库中的 CDN 示例 index.html 正是采用这一方式加载 Roboto 的，可与下文 CDN 方案对照阅读。

图标（Icons）

若需要使用字体版 Icon 组件或预构建的 SVG 版 Material Icons，必须先引入 Material Icons 字体，两种方式任选其一：

方案一：npm 安装预构建图标包

npm install @mui/icons-material

pnpm add @mui/icons-material

yarn add @mui/icons-material

该包对应仓库中的 packages/mui-icons-material 目录，包含按图标划分的模块化导出（如 Home、Search 等），支持 tree-shaking，避免引入整个图标库。

方案二：Google Web Fonts CDN

在 <head /> 中添加 Material Icons 字体：

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/icon?family=Material+Icons"
/>

字体加载后，<Icon>home</Icon> 这类用法即可正常渲染。

通过 CDN 快速体验（免构建）

如果你不想搭建前端工程化环境，可以直接通过 CDN 使用 Material UI，这是快速原型验证的理想方式。仓库内提供了完整可运行的示例：examples/material-ui-via-cdn。

该示例的 index.html 采用了现代浏览器原生能力组合：

1. 通过 <link> 标签从 Google Fonts 加载 Roboto（300/400/500/700）与 Material Icons 字体；
2. 使用 <script type="importmap"> 将 react、react-dom、@mui/material 映射到 esm.sh 的 ESM 构建，并通过 ?external=react,react-dom 参数保证 React 实例唯一；
3. 借助 Babel standalone 在浏览器中即时编译 type="text/babel" 脚本中的 JSX；
4. 脚本内演示了完整的最小应用形态：createTheme 创建主题（含 cssVariables: true）、ThemeProvider 包裹、CssBaseline 重置样式、Container/Box/Typography 布局，最后用 createRoot 渲染到 #root。

目录中还提供了 react-18-example.html，供 React 18 项目参考对应的导入方式。

生产环境警告：官方不推荐在生产环境使用 CDN 方式。它要求客户端下载整个组件库——无论实际用到了哪些组件——这会显著增加首屏体积、拖慢加载速度并浪费带宽。生产项目请使用包管理器安装以获得按需打包能力。

安装路径速查表

场景	必需包	额外配置
默认方案（Emotion）	@mui/material @emotion/react @emotion/styled	React 18 及以下需对齐 react-is
styled-components 方案	@mui/material @mui/styled-engine-sc styled-components	bundler alias 替换 @mui/styled-engine；不建议用于 SSR
字体	@fontsource/roboto（300/400/500/700）	Google Web Fonts <link> 替代
图标	@mui/icons-material	Material Icons 字体 CDN 替代
快速原型	CDN（esm.sh + importmap + Babel standalone）	仅限原型，勿用于生产

小结

Material UI 的安装以「@mui/material + Emotion 双包 + React 17–19」为最小集，其余决策点只有两个：样式引擎（Emotion 或 styled-components）与字体/图标接入方式（npm 包或 Google Fonts CDN）。仓库源码给出的关键约束是：@mui/material@9.x 依赖 react-is@^19（packages/mui-material/package.json），低版本 React 项目必须显式对齐；styled-components 适配包要求 styled-components@^6 且引擎版本与主包主版本一致（packages/mui-styled-engine-sc/package.json）。按上述清单操作，即可覆盖绝大多数项目的安装场景。