Rollup构建React组件库重导出MUI Stepper组件样式缺失问题

基于 React、Storybook、TypeScript 与 Material UI 搭建组件库，核心目标之一是对 MUI 引入的组件添加少量自定义配置后重导出。当前重导出的 Stepper 组件在其他 React 应用中使用时无法按预期渲染，激活步骤的CSS样式、步骤连接器等部分样式与内部组件完全丢失，但按照官方文档相同用法使用原生 MUI Stepper 组件时可正常运行。

Stepper 组件代码（Stepper.tsx） #

import Stack from '@mui/material/Stack';
import MUIStepper, { StepperProps } from '@mui/material/Stepper';

const Stepper = (props: StepperProps) => {
    return (
        <Stack sx={{ width: '100%' }} spacing={4}>
            <MUIStepper {...props}></MUIStepper>
        </Stack>
    );
};

export default Stepper

Rollup 构建插件列表 #

import babel from '@rollup/plugin-babel';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import postcss from 'rollup-plugin-postcss';
import filesize from 'rollup-plugin-filesize';
import autoprefixer from 'autoprefixer';
import typescript from "rollup-plugin-typescript2";
import dts from "rollup-plugin-dts";

问题核心出在 Rollup 构建配置缺失外部依赖声明：

• 构建时未将 React、MUI、Emotion 等依赖标记为外部依赖，导致 MUI 相关代码被直接打包进组件库产物
• 业务项目加载组件库时会出现两份 MUI 运行时代码，MUI 上下文、样式注入逻辑冲突，Stepper 内部的 Step、StepConnector 等子组件无法从父级 Stepper 拿到激活状态、配置参数，最终出现样式丢失、子组件不渲染的问题
• 组件本身的 props 透传逻辑不会触发该类全局样式丢失问题，仅在自定义 children 传递场景下可能存在边界问题

• 在 Rollup 配置中添加外部依赖声明，禁止将 React、MUI、Emotion 相关代码打入组件库产物

  // rollup.config.js 新增配置项
  export default {
    // 保留原有 input、output 等配置
    external: [
      'react',
      'react-dom',
      /^@mui\//,
      /^@emotion\//
    ],
    plugins: [
      // 保留原有插件配置，无需改动
    ]
  }
  

• 在组件库的 package.json 中配置 peerDependencies，明确要求使用方安装对应版本的基础依赖

  {
    "peerDependencies": {
      "react": "^17.0.0 || ^18.0.0",
      "react-dom": "^17.0.0 || ^18.0.0",
      "@mui/material": "^5.0.0",
      "@emotion/react": "^11.0.0",
      "@emotion/styled": "^11.0.0"
    }
  }
  

• （可选优化）调整 Stepper 组件实现，显式透传 children，避免自定义步骤内容传递的边界问题

  import Stack from '@mui/material/Stack';
  import MUIStepper, { StepperProps } from '@mui/material/Stepper';
  
  const Stepper = (props: StepperProps) => {
      const { children, ...restProps } = props;
      return (
          <Stack sx={{ width: '100%' }} spacing={4}>
              <MUIStepper {...restProps}>
                  {children}
              </MUIStepper>
          </Stack>
      );
  };
  
  export default Stepper
  

补充：如果完成上述配置后仍存在样式异常，可检查业务项目是否存在多版本 MUI 依赖共存的问题，通过包管理器的依赖去重能力锁定项目内单版本 MUI 即可解决。

内容的提问来源于stack exchange，提问作者Catalin-Ioan Narita