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

遇到这种情况，血泪教训是调试起来是真的头疼。我以前也遇到过类似的问题，最后发现有时候是CSS或者是全局样式搞的鬼。你可以先检查一下是否有全局样式影响到了你的按钮组件，特别是定位或者隐藏相关的样式。

另一个可能是你的Button组件内部有问题，虽然你提到其他组件没事，但还是有可能是你这个组件内部有逻辑错误或者未处理的异常情况。可以试着简化你的Button组件，看看能不能正常显示，比如去掉一些复杂的逻辑或者props，一步一步排查。

还有一种可能是你的Storybook配置或者环境出了问题，不过既然其他组件能正常工作，这种可能性小一点，但也不排除。你可以尝试重新安装依赖或者更新一下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，对着空白页面发呆两个小时……真不想再经历第二次。