Storybook Addons插件在Vue组件中无法渲染，该怎么排查？

码农国玲提问于 2026-02-07 14:35:32 阅读 89

工具

最近在用Storybook开发Vue组件时，安装了@storybook/addon-essentials后，组件预览区域直接显示空白。之前单独运行组件没问题，但加上参数装饰器后就出错了。

我尝试在按钮组件的Story里这样配置：


// Button.stories.js
import { Meta } from '@storybook/addon-docs';
import Button from './Button.vue';

export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    controls: { expanded: true },
    essential: true // 这里是不是有问题？
  }
} satisfies Meta;

export const Primary = () => ({
  components: { Button },
  template: '<Button>Click me</Button>',
});

控制台没有报错，但预览区就是空白。已经试过删除node_modules和.storybook缓存，重新安装依赖还是不行。是不是Addon配置顺序有冲突？或者需要额外导入某些模块？

Addons插件

我来解答赞 13 收藏

反馈

2 条解答

极客好妍 Lv1

你这个问题核心出在 essential: true 这个参数上，不是配置顺序的问题，而是 Storybook 的 Addons 参数写法搞错了。

essential: true 是 addon-essentials 里用于控制哪些插件默认启用的配置，但它应该写在 addons 字段里，而不是 parameters 里。你这么写在 parameters 里，Storybook 会把它当成组件的参数透传给 Vue 组件，结果 Vue 里没处理这个参数，直接忽略了，但更严重的是——某些版本的 Storybook 在解析这种非法参数时会静默失败，导致整个渲染流程中断，页面就白了。

另外你用的是 export default { ... } satisfies Meta;，说明你用的是 Storybook 7 的新写法（Vite + Vue3 + Composition API），那正确的写法应该是这样优化一下：

Button.stories.js 里改成：

import Button from './Button.vue';



export default {

  title: 'Components/Button',

  component: Button,

  parameters: {

    controls: { expanded: true }

  },

  tags: ['autodocs']

};



export const Primary = {

  render: (args) => ({

    components: { Button },

    setup() {

      return { args };

    },

    template: '<Button v-bind="args">Click me</Button>'

  }),

  args: {}

};

重点改了两处：

一是把 essential 配置删了，它不该出现在这里；
二是把 Primary 从函数写法改成对象写法（Storybook 7 推荐用 render 函数），这样更稳定，尤其配合 Vue3 的 Composition API。

如果你坚持用函数写法，那也得改成：

export const Primary = () => ({

  components: { Button },

  template: '<Button>Click me</Button>'

});

别加任何参数，先确认能渲染出来，再逐步加 args。

另外顺带确认下你的 .storybook/main.js 里是不是这样写的：

export default {

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

  addons: [

    '@storybook/addon-essentials',

    '@storybook/addon-interactions',

    '@storybook/addon-docs'

  ],

  framework: {

    name: '@storybook/vue3-vite',

    options: {}

  }

};

framework 配置对不上也会导致组件不渲染，但一般会报错，你没报错更可能是前面那个参数写错的问题。

先按上面改一下试试，90% 概率能解决。

2026-02-26 08:14

Mc.静薇 Lv1

你这个配置里用的是@storybook/addon-essentials，但代码里没导入它。虽然名字叫“essential”，但需要手动引入。在预览文件或者主配置文件加一下：

import '@storybook/addon-essentials';

另外你那个参数配置里的 essential: true 是多余的，可以删掉。addons默认都会生效。

2026-02-07 15:20