Storybook中使用@storybook/addon-essentials时为什么某些面板显示空白？

一柯言提问于 2026-02-11 20:58:23 阅读 74

工具

我在React项目里配置Storybook后，按照文档引入了@storybook/addon-essentials，但Docs面板和A11y检查这些组件始终显示空白区域。已经确认在main.js里添加了

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

，也尝试过删除.node_modules重新安装，重启Storybook还是没效果，这是配置顺序问题吗？

我来解答赞 10 收藏

反馈

2 条解答

Mc.冰杰 Lv1

这个问题我之前也踩过坑，不是配置顺序的问题，大概率是 Docs 面板的默认渲染器没生效，或者和 React 版本不兼容导致静默失败。

先确认你用的 Storybook 版本，如果是 v7+，记得 main.js 里用的是 framework + addons 分开写的，不是老的 stories 数组那种写法。

重点检查 main.js 配置是否像这样：

module.exports = {

  framework: '@storybook/react-vite', // 或 @storybook/react-webpack5，必须和你项目构建工具匹配

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

  addons: [

    '@storybook/addon-essentials',

    '@storybook/addon-onboarding',

    '@storybook/addon-links',

  ],

};

注意 framework 必须显式指定，而且和你项目里用的构建工具一致。如果用的是 Vite 但没配 react-vite，Docs 面板就会白屏，还不会报错。

另外，如果项目里用了 preview.js，检查有没有手动覆盖 docs 配置导致禁用了默认渲染器，比如这种：

export const parameters = {

  docs: {

    // 删掉这一行，除非你真要自定义 renderer

    // renderer: require('@storybook/addon-docs/blocks').Mdx1Renderer,

  },

};

最后，如果以上都没问题，试试在 .storybook 目录下建个空的 manager.js 文件（哪怕内容为空），有时候 Storybook 的热更新会漏掉插件注册，这个文件能强制触发重载。

性能上这个方案最稳，比你反复重装 node_modules 快多了。

2026-02-26 11:01

W″瑞瑞 Lv1

你这个应该是配置方式错了，@storybook/addon-essentials 现在不需要手动 register。你现在用的写法是老版本的，现在新版直接加包名就行。

把 main.js 里的 addons: ['@storybook/addon-essentials/register'] 改成 addons: ['@storybook/addon-essentials'] 就行了。

另外确认一下 package.json 里装的是正确版本：

npm install --save-dev @storybook/addon-essentials

然后检查 .storybook/main.js 最基本结构是不是对的：

module.exports = {

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

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

};

还有个坑是如果你用了自定义 webpack 配置，可能把默认的 rule 给覆盖了，导致 mdx 或 docgen 解析失败，这时候 Docs 面板就会空。可以先注释掉 webpack config 看看能不能恢复。

数据库层面倒是不涉及这事儿，纯前端构建链路的问题。我之前也被这个 register 后缀坑过一次，文档更新了但很多老教程没删干净。

2026-02-11 21:01