Storybook a11y 插件安装与启用全指南：三步为 Storybook 接入 @storybook/addon-a11y 无障碍测试

导读：本指南基于 Storybook 官方文档中的 addon-a11y-install.md 配置片段，系统讲解在现有 Storybook 项目中安装、注册并验证 @storybook/addon-a11y（无障碍 / accessibility 测试插件）的完整流程。读完本文，你将掌握 npm / pnpm / Yarn 三种包管理器下的手动安装命令、一行 CLI 自动安装方式、在 .storybook/main.js|ts 中的注册写法，以及安装成功后如何确认插件生效并进入后续的 a11y 规则配置与自动化测试工作流。

安装前：认识 @storybook/addon-a11y

@storybook/addon-a11y 是 Storybook 官方提供的无障碍测试插件，它建立在 Deque 的 axe-core 之上，在 Storybook 渲染组件时自动对已渲染的真实 DOM 运行 WCAG 规则审计，作为 UI 可访问性的第一道自动化质检防线。

从当前仓库的 code/addons/a11y/package.json 可以看到它的几个关键事实：

• 核心依赖为 axe-core（^4.2.0），所有检测规则均来自该库；
• 通过 storybook 作为 peerDependencies 与主框架解耦；
• 在 storybook 元信息（displayName: "Accessibility"）中标明其不支持 react-native 框架（unsupportedFrameworks: ["react-native"]）；
• 插件本身是框架无关的，官方 keywords 覆盖 React、Vue、Angular、Svelte、web-components 等主流渲染器。

因此，无论你使用 react-vite、vue3-vite、angular、nextjs 还是 web-components-vite，安装与注册方式都是统一的。

一、手动安装插件包

官方安装片段 addon-a11y-install.md 提供了三种包管理器下的标准安装命令。它们都将插件作为**开发依赖（devDependency）**安装，因为 a11y 检查只服务于本地开发与测试流程，不需要打进生产包。

npm

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

pnpm

pnpm add --save-dev @storybook/addon-a11y

yarn

yarn add --dev @storybook/addon-a11y

三种命令行为完全等价，均会将 @storybook/addon-a11y 写入 package.json 的 devDependencies 并锁定版本。建议直接使用当前项目的既定包管理器（可从仓库根目录的 package.json 与 yarn.lock / bunfig.toml 等文件判断），避免混用导致 lockfile 不一致。

二、更省事的替代方案：storybook add 自动安装

如果不想手动编辑配置文件，Storybook 还提供了自动化安装命令。仓库内 addon-a11y-add.md 以及 code/addons/a11y/README.md 中的示例一致给出如下用法：

npm

npx storybook add @storybook/addon-a11y

pnpm

pnpm exec storybook add @storybook/addon-a11y

yarn

yarn exec storybook add @storybook/addon-a11y

执行该命令时，storybook CLI 会自动完成两件事：安装依赖，并把插件追加到 .storybook/main.js|ts 的 addons 数组中。完整流程说明见官方文档 docs/addons/install-addons.mdx。

不过需要留意一个已知限制（官方文档已在 docs/addons/install-addons.mdx 中以警告形式说明）：当 storybook add 一次指定多个插件时，当前实现只会安装第一个被指定的插件。因此若需一次性引入多个插件，要么分多次执行 add 命令，要么退回手动方式自行编辑配置文件。

三、手动注册：把插件挂载进 addons 数组

手动安装后，插件并不会自动生效。你必须在 Storybook 的配置文件 .storybook/main.js 或 .storybook/main.ts 中，通过 addons 数组把它显式注册进去。这是官方文档中与本安装片段配套的配置片段 addon-a11y-register.md 所展示的核心步骤。

以最常见的 JS + TypeScript 两种写法为例：

.storybook/main.js

export default {
  // Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other Storybook addons
    '@storybook/addon-a11y', //👈 The a11y addon goes here
  ],
};

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other Storybook addons
    '@storybook/addon-a11y', //👈 The a11y addon goes here
  ],
};

export default config;

配置要点说明：

• 在 main.js|ts 的 addons 数组中以包名字符串形式添加即可，无需 import 路径；字符串写法对应包导出的 ./preset / ./manager / ./preview 等多个入口，Storybook 会在启动时自动按需加载。
• 官方还提供了基于新式 defineMain API 的等价写法（针对 react、vue3-vite、angular、web-components-vite 等渲染器，入口形如 @storybook/your-framework/node），TypeScript 与 JavaScript 皆可，详见 addon-a11y-register.md 中的多 tab 示例。
• 若当前项目尚未配置过插件，只需保证 addons 数组中存在 '@storybook/addon-a11y' 这一项即可；通常建议把它与项目里其他既有插件（如 @storybook/addon-docs、@storybook/addon-essentials 等）并列放置。

插件为何能“注册即生效”：源码视角

从仓库的 code/addons/a11y/package.json 的 exports 字段可以看出，a11y 插件对外暴露了三条关键入口：

• ./manager：UI 管理端入口，编译为 dist/manager.js，负责在 Storybook 界面上渲染 Accessibility 面板与工具栏；
• ./preview：预览端入口，编译为 dist/preview.js，负责在 iframe 渲染区内执行自动化检测；
• ./preset：预设入口，编译为 dist/preset.js，用于向构建管线注入必要的配置。

仓库根目录的 code/addons/a11y/preset.js、code/addons/a11y/manager.js 与 code/addons/a11y/preview.js 三行文件即是对 dist/ 产物的再导出，而真正的实现源码位于 code/addons/a11y/src/，包括 manager.tsx（面板注册）、preview.tsx（运行器接线）、a11yRunner.ts（axe-core 驱动）等。把它写进 addons 数组，等同于让 Storybook 在启动时加载 manager 端与 preview 端，从而打通“渲染组件 → 运行 axe 检测 → 面板展示结果”的完整链路。

四、安装成功的验证：重跑 Storybook

编辑完 .storybook/main.js|ts 后，重新启动 Storybook 开发服务器（通常为 npm run storybook）。当你导航到任意 story 时，a11y 插件会自动开始运行并呈现两处可见功能：

1. 工具栏新增无障碍相关控件：包括用于手动触发的检测开关，以及模拟不同视觉障碍（如色盲、视力模糊等）的 Vision Simulator（对应源码 code/addons/a11y/src/VisionSimulator.tsx 与 withVisionSimulator.ts）。
2. Accessibility 检测面板：自动化结果在此汇总，分为三个子标签（详见官方文档 docs/writing-tests/accessibility-testing.mdx）：
   • Violations：明确违反 WCAG 规则及最佳实践的问题；
   • Passes：确认通过的检测项；
   • Incomplete：无法自动判断、需要人工复核的区域。

下方截图展示的是插件在完成安装与注册后、Storybook 界面中出现的 Accessibility 检测能力（图片出处与 docs/addons/install-addons.mdx 安装章节一致）：

若重启后未出现 Accessibility 面板，请依次检查：包是否确实写入 devDependencies、.storybook/main.js|ts 中 addons 数组是否包含 '@storybook/addon-a11y'、以及 Storybook 与插件版本是否兼容（插件以 storybook 为 peer 依赖，两者应保持在同一主版本线）。

五、安装之后：快速配置与落地建议

安装本身只是第一步。插件默认行为是在访问每个 story 时自动运行 a11y 检测；如需控制检测范围、规则集与测试行为，可在 parameters.a11y 上配置。常用参数（详见 docs/writing-tests/accessibility-testing.mdx）：

属性	默认值	说明
parameters.a11y.context	'body'	传给 axe.run 的上下文，决定对哪些元素执行检测
parameters.a11y.config	默认禁用 region 规则	传给 axe.configure() 的配置，常用于逐条调整规则
parameters.a11y.options	{}	传给 axe.run 的选项，可用于更换规则集（如按 runOnly 切换 WCAG 2.2 AA / AAA）
parameters.a11y.test	undefined	与 Vitest 插件 / test-runner 配合时决定测试行为
globals.a11y.manual	undefined	设为 true 可关闭访问 story 时的自动检测（面板中仍可手动触发）

其中 parameters.a11y.test 支持三种值：'off'（不跑自动化 a11y 测试）、'todo'（把违规降级为 UI 中的警告提示，便于留待后续修复）、'error'（违规即视为测试失败，适用于本地与 CI 严格把关）。

官方文档还给出了一个渐进式落地建议：先在项目级 .storybook/preview.* 中把测试行为设为 'error' 以对全部新 story 强制达标；再对存量存在问题的组件临时设 'todo' 保持可见但不阻塞；随后从 Button 这类基础组件开始逐一修复并移除参数，逐步实现“零无障碍违规”的基线。相关配套配置片段（如 addon-a11y-config-in-preview.md、addon-a11y-parameter-error-in-preview.md、addon-a11y-parameter-todo-in-meta.md、addon-a11y-parameter-remove.md）均可直接参考。

六、卸载与移除

若需要移除 a11y 插件，官方同样提供了自动与手动两条路径（详见 docs/addons/install-addons.mdx）：

• 手动移除：反向执行安装流程即可——先从 devDependencies 卸载依赖（如 npm uninstall @storybook/addon-a11y），再删除 .storybook/main.js|ts 的 addons 数组中对应条目。
• CLI 自动移除：借助 storybook remove 命令，CLI 会同时完成卸载依赖与更新配置：

npx storybook remove @storybook/addon-a11y

pnpm exec storybook remove @storybook/addon-a11y

yarn exec storybook remove @storybook/addon-a11y

小结

安装并启用 @storybook/addon-a11y 只需三步：用对应包管理器安装到 devDependencies → 在 .storybook/main.js|ts 的 addons 数组中注册 → 重启 Storybook 查看 Accessibility 面板。追求效率时可用 npx storybook add @storybook/addon-a11y 一步到位（注意其一次只能处理一个插件的限制）。插件基于 axe-core 在真实渲染的 DOM 上执行 WCAG 审计，可配合 Vitest 插件或 test-runner 把 a11y 检测接入本地与 CI，是无障碍质量保障链路中成本最低的第一道关卡。

如需进一步阅读，可继续深入：docs/addons/install-addons.mdx（通用安装指南）、docs/writing-tests/accessibility-testing.mdx（检测、配置与 CI 集成）、code/addons/a11y/（插件完整源码与包元数据）。