axe-core 安装后需确保 DOM 就绪、document 可访问，禁用无 DOM 环境调用；Jest 用 jsdom、Cypress 用 cypress-axe；组件须挂载后测试；应触发交互态再扫描，限定容器范围，慎禁规则；aria-label 与 role 需语义匹配且补全交互逻辑；CI 失败多因样式未注入或 jsdom 版本低。
axe-core 安装与基础集成是否成功？
安装后不等于能用，常见失败点是环境没加载或上下文缺失。直接 npm install axe-core --save-dev 后，必须确保测试运行时 DOM 已就绪、document 可访问，且不能在无 DOM 的 Node 环境（如纯 Node 脚本）里调用 axe.run()。
推荐验证方式：
- 在 Jest 测试中用
testEnvironment: 'jsdom'（而非node） - 若用 Cypress，需通过
cypress-axe插件，不能直接 import axe - 在 Vue/React 组件测试中，确保组件已挂载到
document.body或测试容器内，再传给axe.run()
如何避免 false negative：只测 visible 元素？
axe.run() 默认扫描整个 document，但很多无障碍问题只出现在交互态（比如隐藏的 modal、折叠的菜单、disabled 状态的按钮）。如果只渲染初始 DOM，axe 会漏掉这些场景。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 显式触发状态变化：例如点击 toggle 按钮后再调
axe.run() - 用
axe.run(container)限定范围，避免干扰项（如第三方脚本注入的 DOM） - 禁用无关规则可减少噪音，例如：
{ runOnly: { type: 'tag', values: ['wcag2aa'] } }，但别关掉color-contrast或label
为什么 aria-label 和 role 常被误配？
开发者常以为加了 aria-label 就万事大吉，但 axe 会报错：比如 aria-label 写在 div 上却没设 role，或用了 role="button" 却没处理键盘事件（Enter/Space）。
关键判断逻辑：
- 装饰性图标（如纯 SVG 图标）必须有
aria-hidden="true"或role="img"+aria-label - 交互元素若语义化标签缺失（如
span模拟按钮），必须同时满足：role+tabindex="0"+ 键盘事件监听 +aria-pressed/aria-expanded等状态属性 -
title属性对屏幕阅读器支持极弱，不能替代aria-label或alt
CI 中 axe 测试总失败？排查优先级
CI 环境里 axe.run() 失败，90% 不是代码问题，而是环境差异。本地能过、CI 报 color-contrast 违规，大概率是 CI 渲染器没加载 CSS。
检查顺序：
- 确认测试前已注入样式：Jest 需
jest-css-modules或@testing-library/jest-dom；Cypress 需确保页面 fully loaded - 对比本地与 CI 的浏览器 UA 或渲染引擎版本（如 jsdom 版本太旧，不支持某些 ARIA 属性）
- 临时启用详细报告：
axe.run({ reporter: 'v1' })查看具体违规节点路径，比单纯看violations.length有用得多
真正难搞的是动态颜色系统（比如主题切换后 contrast 实时计算），这种得写自定义 axe 规则，而不是靠开箱即用配置。
