HTML中使用axe-core进行页面无障碍违规问题自动化检测的方法

axe.run() 在纯 HTML 中调用失败的根本原因有三：axe 对象异步挂载未完成、DOM 未渲染完毕、交互状态缺失导致静态扫描无效。

axe.run() 在纯 HTML 里为什么调用失败

直接在 <script> 标签里写 axe.run() 几乎必然失败，不是你代码写错，而是执行时机和环境缺失。常见现象包括：ReferenceError: axe is not defined、TypeError: axe.run is not a function，或静默无输出。

根本原因有三个：

• <script src="axe.min.js"> 加载完成 ≠ axe 对象已挂载到全局 —— 它是异步注入的，需监听 load 事件或用 setTimeout 延迟调用
• DOM 可能还没渲染完，尤其含 <template>、data-* 驱动的模板（如 Alpine.js），axe.run() 扫到的是空壳
• 页面没交互状态（比如折叠菜单未展开、表单未聚焦），而很多无障碍问题只在交互后暴露，静态 DOM 扫不出

DevTools 控制台手动验证是最小可行路径

不改 HTML、不装构建工具、不写测试文件，就能快速确认当前页是否“明显违规”。这是调试阶段最实用的方式。

操作步骤：

立即学习“前端免费学习笔记（深入）”；

• 打开页面 → F12 → Console 标签页
• 先检查：typeof axe，返回 "object" 才继续；否则手动注入：

  const s = document.createElement('script'); s.src = 'https://cdn.jsdelivr.net/npm/[email protected]/dist/axe.min.js'; document.head.appendChild(s);

• 等 2–3 秒，再执行：

  await axe.run({ shadowDom: true }).then(r => console.table(r.violations.map(v => ({ rule: v.id, impact: v.impact, nodes: v.nodes.length }))));

注意：{ shadowDom: true } 必须显式传入，否则自定义元素（如 <my-button>）内部结构完全漏检；若页面含 iframe，还需加 iframes: true。

自动化测试必须绑定生命周期控制权

所谓“自动化”，本质是让 axe.run() 在对的时刻、对的 DOM 状态下运行。这无法靠 setTimeout 模拟，必须依赖测试框架提供的钩子。

主流方案的实际约束：

• Playwright：用 @axe-core/playwright 的 AxeBuilder，它自动等待 networkidle 和 Turbo/ReactPy 渲染完成，但需确保 page.goto() 后显式触发交互（如 page.click('#menu-toggle')）再扫描
• Cypress：必须先 cy.injectAxe()，再用 cy.checkA11y()；直接 cy.window().then(w => w.axe.run()) 会因上下文隔离失败
• Jest + JSDOM：global.document 必须来自新创建的 JSDOM 实例，复用旧实例会导致缓存 DOM，axe.run() 返回过期结果

runOnly 配置不当会让检测失去意义

默认跑全部 57+ 条规则，既慢又干扰重点。但乱配 runOnly 更危险 —— 比如写成 { runOnly: { type: 'tag', values: ['serious'] } }，实际 axe-core 原生根本不识别 serious 这个 tag，结果是“扫了等于没扫”。

安全且常用配置：

• WCAG 2.1 AA 合规：{ runOnly: { type: 'tag', values: ['wcag2aa'] } }
• 只查高影响项（critical / serious）：{ runOnly: ['color-contrast', 'heading-order', 'label', 'link-in-text-block'] } —— 显式列 ID，不依赖 tag
• 排除已知误报（如某些富文本编辑器的 aria-hidden 误判）：{ rules: [{ id: 'aria-hidden-focus', enabled: false }] }

真正容易被忽略的点：所有配置必须在 axe.run() 调用前通过 axe.configure() 设置，且每次测试前重置（axe.reset()），否则上一次的配置会污染后续扫描。