Material-UI 安装配置 #

前置要求 #

在安装 Material-UI 之前，请确保你的项目满足以下要求：

要求	版本	说明
React	>= 17.0.0	推荐 React 18+
Node.js	>= 14.0.0	推荐 LTS 版本
包管理器	npm/yarn/pnpm	任选其一

检查当前环境 #

bash

node -v
npm -v

安装方式 #

方式一：使用包管理器安装（推荐） #

npm #

bash

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

yarn #

bash

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

pnpm #

bash

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

方式二：安装图标库（可选） #

Material Icons 是 MUI 的官方图标库，包含 2000+ 图标：

bash

npm install @mui/icons-material

方式三：安装字体（推荐） #

MUI 默认使用 Roboto 字体：

bash

npm install @fontsource/roboto

然后在入口文件导入：

jsx

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

方式四：使用 CDN（不推荐生产环境） #

html

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

<script src="https://unpkg.com/@mui/material@latest/umd/material-ui.development.js"></script>

完整安装示例 #

创建新项目 #

使用 Vite（推荐） #

bash

npm create vite@latest my-mui-app -- --template react
cd my-mui-app
npm install

使用 Create React App #

bash

npx create-react-app my-mui-app
cd my-mui-app

使用 Next.js #

bash

npx create-next-app@latest my-mui-app
cd my-mui-app

安装 MUI 依赖 #

bash

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

项目配置 #

基础配置 #

在 src/main.jsx 或 src/index.jsx 中配置：

jsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

配置主题 #

创建 src/theme.js：

jsx

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

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
    secondary: {
      main: '#dc004e',
    },
  },
  typography: {
    fontFamily: 'Roboto, Arial, sans-serif',
  },
});

export default theme;

使用 ThemeProvider #

在 src/App.jsx 中：

jsx

import { ThemeProvider, CssBaseline } from '@mui/material';
import theme from './theme';

function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <div className="App">
        <h1>Hello MUI!</h1>
      </div>
    </ThemeProvider>
  );
}

export default App;

TypeScript 配置 #

如果你使用 TypeScript，需要额外配置：

安装类型定义 #

bash

npm install -D @types/react @types/react-dom

tsconfig.json 配置 #

json

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

TypeScript 主题配置 #

src/theme.ts:

tsx

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

declare module '@mui/material/styles' {
  interface Theme {
    status: {
      danger: string;
    };
  }
  interface ThemeOptions {
    status?: {
      danger?: string;
    };
  }
}

const theme = createTheme({
  status: {
    danger: '#e53e3e',
  },
});

export default theme;

样式引擎配置 #

MUI v5 默认使用 Emotion，也支持 styled-components：

使用 styled-components #

bash

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

配置 tsconfig.json 或 package.json：

json

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

项目结构推荐 #

text

my-mui-app/
├── public/
│   └── index.html
├── src/
│   ├── components/
│   │   ├── Button/
│   │   ├── Card/
│   │   └── index.js
│   ├── layouts/
│   │   ├── MainLayout.jsx
│   │   └── AuthLayout.jsx
│   ├── pages/
│   │   ├── Home.jsx
│   │   └── About.jsx
│   ├── theme/
│   │   ├── index.js
│   │   ├── palette.js
│   │   └── typography.js
│   ├── App.jsx
│   └── main.jsx
├── package.json
└── vite.config.js

验证安装 #

创建一个简单的测试组件：

jsx

import { Button, Container, Typography, Stack } from '@mui/material';

function App() {
  return (
    <Container maxWidth="sm" sx={{ mt: 4 }}>
      <Typography variant="h4" gutterBottom>
        MUI 安装成功！
      </Typography>
      <Stack direction="row" spacing={2}>
        <Button variant="contained">Primary</Button>
        <Button variant="outlined">Secondary</Button>
      </Stack>
    </Container>
  );
}

export default App;

运行项目：

bash

npm run dev

常见问题 #

1. 样式不生效 #

确保正确导入 CssBaseline：

jsx

import { CssBaseline } from '@mui/material';

<ThemeProvider theme={theme}>
  <CssBaseline />
  <App />
</ThemeProvider>

2. 字体不显示 #

确保正确导入字体：

jsx

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

3. 图标无法显示 #

确保安装了图标库：

bash

npm install @mui/icons-material

4. TypeScript 类型错误 #

确保安装了正确的类型定义：

bash

npm install -D @types/react @types/react-dom

下一步 #

安装完成后，继续学习快速开始，创建你的第一个 MUI 应用！