用途：在 Playwright 测试中集成 axe-core，自动扫描页面的 WCAG 违规项，适合新增或调试无障碍（a11y）测试、按 WCAG 标签过滤规则、限定扫描范围，以及在 CI 中报告结果。
安装：npm i -D @playwright/test @axe-core/playwright
基本用法：每次扫描都新建 AxeBuilder({ page })，不要跨页面复用。示例：await page.goto('/'); const results = await new AxeBuilder({ page }).analyze(); expect(results.violations).toEqual([]);
Builder 方法：include(selector) 与 exclude(selector) 限定扫描范围，可链式调用；withTags(string | string[]) 按标签限制规则；withRules(string | string[]) 只运行指定规则；disableRules(string | string[]) 跳过规则；options(axeRunOptions) 传入原始 axe.run 选项；setLegacyMode(boolean) 切换旧版 frame 测试；analyze() 返回结果对象。
标签：常用 AA 目标为 ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']。不传 withTags 时 axe 还会运行最佳实践规则，可能因非 WCAG 项导致构建失败。
范围限定：优先用 exclude 排除第三方组件，disableRules 仅用于已有跟踪工单的已知问题，并在旁边注明工单号。
已知限制：color-contrast 无法读取 canvas 或 WebGL 像素，其中文字不被检查，其上的 DOM 文字会报为 incomplete 而非违规；渐变、图片和半透明背景通常进入 results.incomplete，需人工或用截图对比工具复核；被遮挡元素（吸顶导航、弹窗、伪元素覆盖）会产生 incomplete；动画进行中颜色不稳定，应等待稳定或模拟减少动态效果；axe 只看到扫描时的 DOM 状态，菜单、对话框和标签页需先打开。应始终断言 violations，并记录 incomplete 以保留被跳过的对比度检查。
主题：先切换主题再扫描，方式需与应用存储主题的方式一致。可用 page.emulateMedia({ colorScheme: scheme })；若主题是 class 或属性（如 next-themes），用 page.addInitScript 写 localStorage 或点击切换，并等待属性生效后再扫描。
按路由扫描：遍历路由数组，逐个 goto 后 analyze 并断言 violations 为空。
CI 报告：用 testInfo.attach 附加完整结果 JSON，便于从 HTML 报告查看失败；将 violations 映射为可读摘要再断言，使失败差异更清晰；可用 fixture（test.extend）共享标签与排除配置。
注意：axe 只能发现部分 WCAG 失败，绿色扫描仅代表“未检测到违规”，不等于合规；键盘、焦点顺序和屏幕阅读器检查仍需人工完成。