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/axe-core@4.7.0/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()），否则上一次的配置会污染后续扫描。
