MUI System 安装指南：@mui/system 与 Emotion / styled-components 样式引擎配置详解

2026-09-06 18:01:27作者：宗隆裙

本文讲解如何在项目中安装 MUI System（@mui/system）这一套用于快速搭建自定义布局的 CSS 工具库：先介绍基于默认 Emotion 引擎的标准安装方式与 React 版本要求，再给出改用 styled-components 引擎的替代安装方案，并结合当前仓库（v9.4.0）的源码与 package.json 配置，说明每个依赖包的作用、版本约束以及服务端渲染场景下的选型限制。读完本文，你可以独立完成两种引擎下的完整安装，并理解安装命令背后各依赖包的实际职责。

一、MUI System 是什么

MUI System 是一组 CSS 工具集，帮助开发者更高效地构建自定义设计（custom designs），使快速搭建自定义布局成为可能。它是 Material UI 等库内部使用的样式底层能力，被单独抽离发布为 @mui/system 包。

从包元信息看（packages/mui-system/package.json）：

当前仓库中 @mui/system 的版本为 9.4.0，许可证为 MIT；
官方对它的定义是："MUI System is a set of CSS utilities to help you build custom designs more efficiently. It makes it possible to rapidly lay out custom designs."；
运行环境要求 engines.node >= 14.0.0。

安装它之后，你可以直接使用 Box、Container、Grid、Stack 等布局组件，并通过 sx prop 在组件内直接写样式，而不必为每个组件创建额外的 styled-component 定义。这一点可以从入口文件 packages/mui-system/src/index.js 的导出确认：它导出 Box、Container、Grid、Stack、createTheme、styled、useTheme、useMediaQuery 等核心 API，并在第 1 行直接从 @mui/styled-engine 转出 css、keyframes、StyledEngineProvider——这正体现了"样式引擎"是可插拔的架构设计，也是后文两种安装方式的分水岭。

二、默认安装（Emotion 引擎）

执行以下任一命令即可将 MUI System 加入项目（npm / pnpm / yarn 三选一）：

# npm
npm install @mui/system @emotion/react @emotion/styled

# pnpm
pnpm add @mui/system @emotion/react @emotion/styled

# yarn
yarn add @mui/system @emotion/react @emotion/styled

MUI System 默认的样式引擎是 Emotion，因此安装命令中除了 @mui/system 本身，还需要带上 @emotion/react 与 @emotion/styled 两个包。

Peer 依赖：React 版本要求

请注意 react 是一个 peer dependency，意味着在安装 MUI System 之前，你应该确保项目中已经安装了 React。当前仓库声明的 React 版本要求为：

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
}

即 React 17、18、19 三个大版本均受支持。

从 packages/mui-system/package.json 的完整 peer 依赖声明看，还可以获得两个更精确的版本约束：

Peer 依赖	版本要求	是否必须
`react`	`^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0`	必须
`@emotion/react`	`^11.5.0`	可选（`peerDependenciesMeta` 中标记为 `optional: true`）
`@emotion/styled`	`^11.3.0`	可选（同上）
`@types/react`	`^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0`	可选

@emotion/react 与 @emotion/styled 之所以是"可选" peer 依赖，正是因为 MUI System 允许通过 @mui/styled-engine-sc 切换到 styled-components 引擎（见下文）。但如果你走默认的 Emotion 路线，这三个包缺一不可，这也是安装命令里同时列出三者的原因。

源码级的依赖链佐证

除了直接依赖，@mui/system 在运行时还会依赖一组 MUI 内部的 workspace 包（见 packages/mui-system/package.json 的 dependencies）：

@mui/styled-engine：Emotion 版 styled API 封装包，其依赖（packages/mui-styled-engine/package.json）中可看到 @emotion/cache、@emotion/serialize、@emotion/sheet——这就是 Emotion 引擎在底层真正工作的三个模块；
@mui/private-theming：提供 ThemeProvider / useTheme 等主题上下文能力；
@mui/utils：提供 clsx 等工具与 React 兼容层；
@mui/types：共享的 TypeScript 类型定义；
clsx、csstype、prop-types：类名合并、CSS 类型与运行时 prop 校验。

因此一条完整的默认安装命令，实际拉起的依赖树是：@mui/system → @mui/styled-engine → @emotion/* 底层包 + React 17/18/19 宿主环境。

三、使用 styled-components 引擎安装

如果项目已经在用 styled-components，并希望 MUI System 也使用同一引擎，则安装命令改为：

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

# pnpm
pnpm add @mui/system @mui/styled-engine-sc styled-components

# yarn
yarn add @mui/system @mui/styled-engine-sc styled-components

与默认安装相比，变化有两点：

去掉了 @emotion/react 和 @emotion/styled；
加入了 @mui/styled-engine-sc 和 styled-components 本身。

@mui/styled-engine-sc 是官方提供的 styled() API 封装包，用于对接 styled-components。从它的包声明（packages/mui-styled-engine-sc/package.json）可以看到，它对 styled-components 的版本要求是 peerDependencies: { "styled-components": "^6.0.0" }，即 styled-components v6 起步，请确保你项目中的 styled-components 版本满足该约束。

其实现位于 packages/mui-styled-engine-sc/src/index.ts：内部的 styled() 函数直接调用 styled-components 的 styled 工厂，并通过 withConfig 透传 MUI 特有的 label（displayName）与 shouldForwardProp 配置；同时文件末尾（packages/mui-styled-engine-sc/src/index.ts）从 styled-components 转出 ThemeContext、keyframes、css，并导出本包的 StyledEngineProvider 与 GlobalStyles。这样 @mui/system 的 styled、css、keyframes、GlobalStyles 等 API 在两个引擎下保持签名一致，业务代码无需感知底层差异。

开发模式下它还带有防御性检查（packages/mui-styled-engine-sc/src/index.ts）：如果你调用 styled("div")() 时忘记传样式参数，控制台会打印 MUI: Seems like you called styled("div")() without a style argument. 的明确报错，帮助定位误用。

四、SSR 场景的选型限制（重要）

自 2021 年末起，styled-components 与服务端渲染（SSR）的 Material UI 项目不兼容。原因是 babel-plugin-styled-components 无法与 @mui 各包内部的 styled() 工具协同工作，相关讨论见 MUI 的 GitHub issue #29742。

因此官方强烈建议：SSR 项目使用 Emotion 引擎（即第二节的默认安装方式），只有纯客户端渲染（CSR）项目才适合选择 styled-components 引擎。选型时可以按以下原则决策：

场景	推荐引擎	安装命令要点
服务端渲染（Next.js、Express SSR 等）	Emotion（默认）	`@mui/system @emotion/react @emotion/styled`
纯客户端渲染且已重度使用 styled-components v6	styled-components	`@mui/system @mui/styled-engine-sc styled-components`

五、安装后的验证与后续使用

安装完成后，可以从 @mui/system 导入核心能力做简单验证，例如：

import { Box, Container, Stack } from '@mui/system';

export default function Demo() {
  return (
    <Container>
      <Box sx={{ p: 2, bgcolor: 'primary.main', color: 'primary.contrastText' }}>
        MUI System installed successfully
      </Box>
    </Container>
  );
}

上述 Box、Container、Stack、sx 的导出均可在 packages/mui-system/src/index.js 中得到确认。

接下来建议继续阅读仓库内 MUI System 的其他入门文档，它们与本篇同属 docs/data/system/getting-started/ 目录：

概览（Overview）：MUI System 的核心概念与 sx prop 介绍；
使用方式（Usage）：sx prop 的响应式断点、函数值等用法；
自定义组件（Custom Components）：基于 MUI System 创建自定义组件。

六、小结

默认安装：@mui/system @emotion/react @emotion/styled，React 需为 17/18/19（peer dependency），引擎默认 Emotion；
styled-components 路线：改为 @mui/system @mui/styled-engine-sc styled-components，且 styled-components 需为 v6；
SSR 项目必须避开 styled-components 路线（引擎与 babel-plugin-styled-components 的兼容性问题），坚持使用 Emotion；
从源码看，引擎的可插拔性由 @mui/styled-engine（Emotion）与 @mui/styled-engine-sc（styled-components v6）两个封装包实现，二者对 styled、css、keyframes、GlobalStyles、StyledEngineProvider 提供一致的外层 API。