为什么我的Storybook故事显示空白页面？

这个问题根本原因是你的 Button 组件内部可能没有正确返回 JSX，或者它依赖的样式根本没有加载进来。我之前也踩过这个坑，尤其是用 CSS-in-JS 或者动态类名的时候。

先别急着改 Storybook 配置，咱们一步步来定位：

第一步，最简单的验证方式是把你的故事改成纯原生 HTML 按钮，看看能不能显示

export const Primary = () => (

  

    Test Button

  

);

如果这个能显示，说明 Storybook 渲染机制本身没问题，问题出在你写的 Button 组件上。

第二步，打开你的 Button.js 文件，检查它的导出是不是对的。有时候你以为导出了默认组件，结果不小心写成了命名导出，或者用了高阶函数包裹但没正确处理。确认一下你是不是这样导出的：

// 正确做法

const Button = ({ children, variant }) => {

  // 注意这里一定要 return，而且不能 return null 或空字符串

  return (

    btn btn-${variant}}>

      {children}

    

  );

};



export default Button;

如果你用了 styled-components、emotion 这类库，那问题很可能出现在样式注入时机上。Storybook 默认不会自动加载你在 App.js 里引入的全局样式或 ThemeProvider。你需要手动在 preview.js 中包裹装饰器。

比如你用了 emotion，就得在 .storybook/preview.js 加上：

import { ThemeProvider } from 'styled-components';

import { GlobalStyles, theme } from '../src/styles'; // 路径按你项目结构调整



export const decorators = [

  (Story) => (

    <>

      

      

        

      

    

  ),

];

第三步，检查你的构建配置。如果你用了 vite 或 webpack 构建 Storybook，有可能 css 文件没被正确识别。特别是当你用的是 CSS modules 或 postcss，需要确保 .storybook/main.js 里配置了对应的 loader。

比如在 main.js 中确认有类似：

module.exports = {

  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],

  addons: ['@storybook/addon-essentials'],

  webpackFinal: async (config) => {

    // 确保 css rule 存在且生效

    config.module.rules.push({

      test: /.css$/,

      use: ['style-loader', 'css-loader'],

      include: path.resolve(__dirname, '../src'),

    });

    return config;

  },

};

最后还有一个隐藏雷区：React 版本不一致。如果你项目里装了多个版本的 react，可能导致 Button 组件虽然渲染了，但 Fiber 树断了，界面看起来就是空白。运行下 npm ls react 或 yarn list react，看看有没有重复安装。

总结一下排查顺序：
1. 先用原生 button 测试 Storybook 能不能渲染内容
2. 检查 Button 组件是否真的 return 了可见元素
3. 看是否有样式丢失（特别是 CSS-in-JS 或主题未注入）
4. 确认 webpack/vite 配置处理了样式文件
5. 排查依赖冲突，尤其是 react 和 react-dom 版本

我上周就是因为忘了在 decorators 里加 ThemeProvider，对着空白页面发呆两个小时……真不想再经历第二次。