axe-core 不能直接在纯 html 页面运行自动化测试，需浏览器上下文、测试框架或 node.js 环境；常见错误因 dom 未就绪或缺少断言机制；最小可运行场景是 devtools 控制台手动执行 axe.run()；自动化必须集成 playwright、vitest/cypress 或 karma；规则需显式配置 wcag 级别、iframe 和 shadow dom 支持。
axe-core 不能直接在纯 HTML 页面里“运行自动化测试”——它需要执行环境（如浏览器上下文、测试框架或 Node.js 运行时）来调用 axe.run() 并读取真实 DOM。 纯静态 HTML 文件双击打开后，axe.run() 会报错或静默失败，因为缺少初始化时机、异步等待能力与测试断言机制。
为什么直接在 HTML 中写 axe.run() 常常没反应
常见错误现象包括：ReferenceError: axe is not defined、TypeError: axe.run is not a function，或控制台无输出但测试未执行。根本原因是：
-
<script src="axe.min.js"></script>加载完成 ≠ axe 已就绪 —— 它依赖 DOM 渲染完成，且某些框架（如 React、Vue）的动态内容需额外等待 - 纯 HTML 没有测试断言（如
expect(results.violations).toHaveLength(0)），即使检测出问题也无法触发失败 - 无障碍问题常出现在交互后（如展开菜单、提交表单），静态 HTML 无法模拟这些状态
真正能跑通的最小可运行场景：浏览器 DevTools 控制台手动验证
这是最轻量、无需构建工具的验证方式，适合快速排查单页问题：
- 确保页面已完全加载（含 JS 渲染），再打开开发者工具 → Console 标签页
- 粘贴并执行：
await axe.run().then(r => console.table(r.violations.map(v => ({ rule: v.id, impact: v.impact, nodes: v.nodes.length })))); - 若报
axe is not defined，先手动注入：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); - 注意：此方式不适用于 CI 或回归测试，仅作调试用
CI/CD 或本地自动化中必须走测试框架集成
要让 axe-core 真正“自动化”，必须绑定到一个能控制页面生命周期、支持断言、可复现状态的测试环境。主流路径只有三种：
-
Playwright + @axe-core/playwright：适合端到端测试，能自动等待 Turbo/ReactPy 等框架渲染完成，
AxeBuilder封装了重试与 iframe 处理逻辑 -
Vitest/Cypress + axe-testing-library：适合组件级快照测试，
toHaveNoViolations断言直接抛错，配合render()可测 React Suite、Buefy 等库的挂载态 -
Karma + karma-axe-core：适合 iView、老 Vue 项目，需在
karma.conf.js中显式加入'axe-core'到frameworks数组，否则插件不激活
容易被忽略的关键点：规则范围与上下文选择
很多人以为 axe.run() 默认查全部，其实默认只检查可见、可聚焦、非隐藏节点，且不包含 iframe 内容。实际使用必须明确：
- 用
runOnly: { type: 'tag', values: ['wcag2aa'] }限定 WCAG 2.1 AA 级，避免误报低优先级规则（如heading-order在 SSR 场景下易假阳性） - 若页面含
<iframe></iframe>，必须传{ included: ['iframe'] }或显式调用axe.run(iframe.contentDocument) - 对 Shadow DOM 组件（如 Theatre 的
<ui-panel></ui-panel>），需启用shadowDom: true配置，否则内部节点全被跳过 - ReactPy/Vue 等框架中，
axe.run()必须在await nextTick()或await page.waitForTimeout(100)后执行，否则拿到的是骨架 DOM
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
