用途
本技能提供 Material UI（MUI）的版本迁移指南，聚焦两条升级路径：v4 → v5 与 v5 → v6。内容以代码示例和命令为主，帮助开发者把旧版 MUI 项目迁移到新版 API。
主要能力
v4 → v5 迁移
- 包重命名：卸载 @material-ui/core、@material-ui/icons、@material-ui/lab、@material-ui/system，安装 @mui/material、@mui/icons-material、@mui/lab、@mui/system，并新增 @emotion/react 与 @emotion/styled 作为必需的同级依赖；若使用 styled-components 则安装 @mui/styled-engine-sc 与 styled-components。
- 官方 codemod：
npx @mui/codemod v5.0.0/preset-safe src/可自动处理约 80% 的机械性改动，也支持对单个文件运行，或单独执行 component-rename-prop、moved-lab-modules、optimal-imports 等转换。 - 导入路径变更：makeStyles 被 styled 取代，createMuiTheme 改名为 createTheme，组件从 @material-ui/core/X 改为 @mui/material/X。
- createTheme 结构调整：v4 的 overrides 与 props 合并为 v5 的 components，分别对应 styleOverrides 与 defaultProps。
- 样式方案转换：给出三种模式——sx prop（简单内联样式）、styled()（可复用样式组件）、tss-react（近似 makeStyles 的替代方案，适合大型代码库）。
- withStyles 转 styled，并说明如何定位内部类名（如 .MuiButton-label）。
- color 属性变化：v5 移除 color="default"，改用 color="inherit" 或省略。
- 系统属性移除：mt、p、bgcolor 等系统属性在 v5 中仅适用于 Box 和 Stack，其他组件需改用 sx。
- Lab 组件迁移：Alert、Autocomplete、Pagination、Rating、Skeleton、SpeedDial、ToggleButton 等从 @mui/lab 升级到 @mui/material。
- 提供 v4 → v5 破坏性变更检查清单。
v5 → v6 迁移
- 官方 codemod：
npx @mui/codemod v6.0.0/preset-safe src/，以及 grid-v2-props、sx-prop 等单项转换。 - Grid v2：v6 默认使用 Grid v2，移除 item 属性，xs/sm/md/lg/xl 合并为 size 对象属性，并新增 offset 属性与 size="grow" 自动填充。
- slots/slotProps 标准化：MUI X 组件（DatePicker、DataGrid、Charts）统一使用 slots/slotProps，移除旧的 components/componentsProps。
- Pigment CSS（v6 实验特性）：可选的构建期 CSS 提取方案，替代 Emotion，实现零运行时样式，附安装与 Next.js 配置示例。
- 提供 v5 → v6 破坏性变更检查清单，包括包版本升级、Grid 属性替换、slots 替换、日期适配器依赖、useMediaQuery 的 theme 参数、Stack divider 间距、DataGrid 列定义字段等。
增量迁移策略
按四个阶段推进：包与配置（更新包、运行 codemod、修复导入错误）、主题迁移（先迁移主题文件）、逐组件迁移（优先高频、替换路径清晰、自包含的组件）、彻底移除 JSS。同时给出 v4 与 v5 共存策略，通过 StylesProvider 与 ThemeProvider 分别包裹两套样式引擎。
转换参考与问题排查
提供 makeStyles 模式到 v5 等价写法的对照表（间距、颜色、断点、伪类、内部类名、过渡等），并列出迁移后常见问题：样式不生效、TypeScript 报错、SSR 样式闪烁（FOUC）、Grid 布局损坏及其排查方向。
使用方式
按版本路径执行对应 codemod 命令，再依据示例逐项调整导入、主题配置与样式写法。大型代码库建议采用分阶段增量迁移，而非一次性全量替换。
适用场景
正在维护 MUI v4 或 v5 项目、计划升级到 v5 或 v6 的前端团队；需要了解破坏性变更范围、评估迁移工作量或制定迁移计划的开发者。
限制
资料未提供具体版本发布时间、官方支持周期、性能基准数据或收费信息。Pigment CSS 在 v6 中标注为实验特性，其稳定性与后续变化暂未提供。