Storybook 的 Accessibility 插件怎么不显示检测结果？

上官浩奇提问于 2026-03-03 23:22:20 阅读 36

工具

我按照官方文档装了 @storybook/addon-a11y，也在 .storybook/main.js 里注册了插件，页面右下角也出现了 a11y 面板，但点进去一直是空白，没有任何检测结果或报错。是我漏了什么配置吗？

我的组件是用 React 写的，已经加了基本的语义化标签，比如 <button> 和 aria-label，但面板还是没反应。试过重启 Storybook 也没用。

module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
  ],
};

我来解答赞 8 收藏

反馈

2 条解答

书生シ凡敬 Lv1

官方文档里说，@storybook/addon-a11y 插件需要一个 AXE 核心库来执行实际的可访问性检查。确保你已经在项目中安装了 axe-core 库。你可以通过 npm 或 yarn 来安装它：

npm install axe-core --save-dev

# 或者

yarn add axe-core --dev

安装完成后，检查你的 Storybook 配置是否正确加载了这个插件。你已经在 main.js 里注册了插件，看起来没问题。接下来，确保你的故事文件中有一些实际的组件渲染出来，因为 a11y 插件需要这些组件来运行检查。

如果一切正常，重启 Storybook 后应该能看到 a11y 面板中有检测结果了。如果问题依旧，尝试清除浏览器缓存或者换个浏览器看看，有时候缓存会导致一些奇怪的问题。

2026-03-25 01:05

端木鑫哲 Lv1

看你的配置代码，问题大概率出在插件重复注册上。官方文档里写得挺清楚，@storybook/addon-essentials 这个包里其实已经内置了 @storybook/addon-a11y。你在 addons 数组里把它俩都写上，会导致同一个面板 ID 被注册两次，后面那个大概率就静默失败了，所以你点开是空白的。

解决方法很简单，把 @storybook/addon-a11y 从配置里删掉就行了，只保留 essentials 就能正常工作。现在的 Storybook 版本只要引入 essentials，a11y 检测是自动跑的，不需要你在 preview.js 里额外加什么 decorator。

修改后的配置大概像这样：

module.exports = {

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

  addons: [

    '@storybook/addon-essentials',

  ],

};

改完记得重启一下 Storybook，再打开面板应该就能看到 axe-core 的扫描结果了。如果这时候还全是空的，那可能真的是你代码写得太完美了，一点违规都没有，或者可以试着写个缺 alt 属性的 img 标签测一下。

2026-03-04 10:29