Storybook搭配MUI v5使用时自动生成文档功能失效问题问询

该问题通常由MUI v5默认的Emotion样式引擎与Storybook Docs插件的渲染逻辑冲突、全局MUI上下文缺失、Props自动生成配置异常三类原因导致，可按以下步骤逐一排查修复：

• 调整Storybook主配置
  在.storybook/main.js中开启自动文档生成功能，参考配置如下：

  module.exports = {
    stories: ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
    addons: [
      "@storybook/addon-links",
      "@storybook/addon-essentials",
      "@storybook/addon-interactions",
    ],
    framework: "@storybook/react",
    docs: {
      autodocs: true
    }
  }
  

• 配置全局MUI上下文装饰器
  在.storybook/preview.js中全局包裹MUI样式引擎与主题提供者，避免组件渲染时上下文丢失导致白屏：

  import React from 'react';
  import { ThemeProvider, createTheme } from '@mui/material/styles';
  import { StyledEngineProvider } from '@mui/material/styles';
  
  const theme = createTheme();
  
  export const decorators = [
    (Story) => (
      <StyledEngineProvider injectFirst>
        <ThemeProvider theme={theme}>
          <Story />
        </ThemeProvider>
      </StyledEngineProvider>
    ),
  ];
  

• 修正组件与Story文件写法
  首先将组件接收的参数透传给内部MUI按钮，确保参数绑定正常：

  export const Button = ({ primary, backgroundColor, size, label, ...props }) => {
    return <MiButton {...props}>{label}</MiButton>;
  };
  

  其次确保Story文件导出格式符合Docs插件解析规则，示例Button.stories.jsx写法：

  import { Button } from './Button';
  
  export default {
    title: 'Example/Button',
    component: Button,
    argTypes: {
      backgroundColor: { control: 'color' },
    },
  };
  
  const Template = (args) => <Button {...args} />;
  
  export const Primary = Template.bind({});
  Primary.args = {
    primary: true,
    label: 'Button',
  };
  

• 排除JSX解析冲突
  如果完成上述操作仍白屏，可在组件文件顶部添加注释/* @jsxImportSource @emotion/react */，或在项目babel配置中添加@emotion/babel-plugin插件，解决Emotion与Storybook默认JSX解析逻辑的冲突。

内容的提问来源于stack exchange，提问作者Jay P