MUI Stepper组件步骤节点图标不显示，按官方示例实现后页面空白问题

以下是对应排查和修复方案：

• 检查是否完整导入所有依赖
  MUI v5版本需要导入以下依赖，漏导会直接导致组件渲染失败页面空白：

import { styled } from '@mui/material/styles';
import Stepper from '@mui/material/Stepper';
import Step from '@mui/material/Step';
import StepLabel from '@mui/material/StepLabel';

如果是MUI v4版本，需要从@material-ui/core导入对应组件，styled要从@material-ui/core/styles导入。

• 检查steps变量是否已定义
  官方示例中省略了steps变量的定义，你需要补充你的步骤配置，比如：

const steps = ['步骤1', '步骤2', '步骤3'];

未定义steps直接调用map方法会抛出JS报错，阻断页面渲染。

• 检查图标引入方式是否正确
  MUI的Icon组件依赖Material Icons字体，若未引入对应字体会导致图标无法渲染，更推荐直接使用@mui/icons-material包的内置图标组件，无需额外引入字体：
  首先安装图标包：npm install @mui/icons-material
  然后将代码中的<Icon>star</Icon>替换为<StarIcon />，同时导入对应图标：import StarIcon from '@mui/icons-material/Star';
• 检查styled用法是否匹配当前MUI版本
  如果是MUI v4，自定义组件传递ownerState的写法不生效，需要把状态直接作为props传递，调整ColorlibStepIconRoot的样式逻辑即可。

修正后完整可运行代码（MUI v5版本） #

import { styled } from '@mui/material/styles';
import Stepper from '@mui/material/Stepper';
import Step from '@mui/material/Step';
import StepLabel from '@mui/material/StepLabel';
import StarIcon from '@mui/icons-material/Star';

// 自定义步骤图标根节点
const ColorlibStepIconRoot = styled('div')(({ theme, ownerState }) => ({
  zIndex: 1,
  color: '#fff',
  width: 50,
  height: 50,
  display: 'flex',
  borderRadius: '50%',
  justifyContent: 'center',
  alignItems: 'center',
  backgroundColor: theme.palette.grey[400],
  ...(ownerState.active && {
    backgroundImage:
      'linear-gradient( 136deg, rgb(242,113,33) 0%, rgb(233,64,87) 50%, rgb(138,35,135) 100%)',
    boxShadow: '0 4px 10px 0 rgba(0,0,0,.25)',
  }),
  ...(ownerState.completed && {
    backgroundImage:
      'linear-gradient( 136deg, rgb(242,113,33) 0%, rgb(233,64,87) 50%, rgb(138,35,135) 100%)',
  }),
}));

function ColorlibStepIcon(props) {
  const { active, completed, className, icon } = props;

  const icons = {
    1: <StarIcon />,
    2: <StarIcon />,
    3: <StarIcon />,
  };

  return (
    <ColorlibStepIconRoot ownerState={{ completed, active }} className={className}>
      {icons[String(icon)]}
    </ColorlibStepIconRoot>
  );
}

// 组件内使用
export default function CustomStepper() {
  const steps = ['选择方案', '填写信息', '完成创建'];
  return (
    <Stepper alternativeLabel activeStep={2} style={{ background: 'none' }}>
      {steps.map((label) => (
        <Step key={label}>
          <StepLabel StepIconComponent={ColorlibStepIcon}>{label}</StepLabel>
        </Step>
      ))}
    </Stepper>
  )
}

内容的提问来源于stack exchange，提问作者Kenny Quach