Material UI v0.x 迁移至 v1.x 迁移步骤指南请求

Hey there! I’ve helped a few teams make the jump from Material UI v0.x to v1.x, so I know it feels daunting at first—but breaking it into clear, actionable steps makes it totally manageable. Here’s a detailed guide to walk you through the process:

一、前期准备 #

• First things first: back up your code or create a dedicated migration branch. You don’t want to mess up your working production code mid-migration!
• Check your React version: Material UI v1.x requires React 16.3.0 or higher. If your project is on an older version, upgrade it first with npm install react@latest react-dom@latest (or yarn equivalents).
• Uninstall the old Material UI package: Run npm uninstall material-ui or yarn remove material-ui to clear out the deprecated version.

二、安装v1.x依赖 #

• Install the core v1.x library: npm install @material-ui/core or yarn add @material-ui/core
• If you used icons in v0.x, you’ll need the new icon package: npm install @material-ui/icons or yarn add @material-ui/icons (the old icon set isn’t compatible with v1.x)
• For custom styling and theming, install @material-ui/styles if you need advanced style solutions (though v1.x has built-in hooks like makeStyles that work great too)

三、组件迁移（核心环节） #

V1.x basically rewrote component APIs, so this is where you’ll spend most of your time:

• 导入路径与组件重命名:
  • 旧写法: import RaisedButton from 'material-ui/RaisedButton' → 新写法: import Button from '@material-ui/core/Button'（通过variant="contained"实现凸起效果）
  • 旧FlatButton → 新Button（默认variant="text"，和旧扁平样式一致）
  • IconButton保留，但导入路径改为@material-ui/core/IconButton
  • 卡片组件全面重构：Card、CardMedia、CardContent等的props和用法更规范，建议对照组件细节调整
• Props属性调整:
  • 颜色属性：不再用primary={true}，改为字符串格式color="primary"或color="secondary"
  • 尺寸属性：small/large改为size="small"/size="large"
  • 事件处理：移除onTouchTap，改用标准React事件如onClick
• 主题系统重构:
  • MuiThemeProvider和getMuiTheme被替换为ThemeProvider和createTheme
    代码示例对比：

  // v0.x
  import { MuiThemeProvider, getMuiTheme } from 'material-ui/styles';
  const customTheme = getMuiTheme({
    palette: { primaryColor: '#2196f3' }
  });
  
  // v1.x
  import { ThemeProvider, createTheme } from '@material-ui/core/styles';
  const customTheme = createTheme({
    palette: { primary: { main: '#2196f3' } }
  });
  

  主题结构有变化，需要调整自定义配置以匹配v1.x的调色板和排版规范。

四、样式迁移 #

• V0.x的内联样式和styleName（若使用CSS Modules）被Material UI的钩子式样式替代：

  // v1.x makeStyles示例
  import { makeStyles } from '@material-ui/core/styles';
  
  const useStyles = makeStyles({
    container: {
      padding: '1rem',
      backgroundColor: '#f5f5f5'
    }
  });
  
  function MyComponent() {
    const classes = useStyles();
    return <div className={classes.container}>Hello World</div>;
  }
  

• 若要全局覆盖组件样式，建议在createTheme的overrides中配置，而非直接修改全局CSS，这样更符合Material UI的设计体系且易于维护。

五、增量测试（别着急！） #

• 不要试图一次性迁移整个应用！先从单个页面或小组件开始，确保功能正常后再推进。
• 必要时可以临时同时运行v0.x和v1.x，只需通过各自路径导入组件：

  import OldButton from 'material-ui/RaisedButton';
  import NewButton from '@material-ui/core/Button';
  

  这样可以逐个替换组件，避免破坏现有应用。
• 留意浏览器控制台：v1.x会抛出有用的警告提示，比如使用了废弃props或模式，跟着提示修复问题即可。

六、最终清理 #

• 所有组件迁移完成后，彻底卸载旧的material-ui包。
• 全面检查所有交互：表单、模态框、响应式布局以及基于Material UI构建的自定义组件。
• 确认你使用的第三方库兼容v1.x——部分旧包可能依赖v0.x的API。

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