axe-core CLI 不能直接扫描纯静态 HTML 文件检测动态内容，必须配合 Puppeteer 启动真实浏览器或配置 --legacy 等参数；对多页应用需遍历所有 HTML 输出文件，且需显式启用 WCAG 2.2 规则、禁用误报规则并设 failOnViolation 控制构建失败阈值。
用 axe-core CLI 扫描本地 HTML 文件
axe-core 是目前最可靠的可访问性检测引擎，它的 CLI 版本能脱离浏览器直接读取 HTML 文件并输出结构化报告。关键不是“跑起来”，而是让它真正覆盖你工程中所有可能被忽略的入口页。
常见错误现象：运行 axe index.html 却只报出 0 个问题，实际页面里有大量无 alt 的图片或缺失 label 的表单——这是因为 CLI 默认只检查「渲染后 DOM」，而纯静态 HTML 没执行 JS，某些动态插入的内容根本没被加载。
- 必须加
--disable-colors --legacy参数避免 ANSI 控制符干扰 CI 日志解析 - 若页面依赖 JS 初始化（比如 React/Vue 渲染），得先用 Puppeteer 启动真实浏览器再注入 axe，不能只靠 CLI 直扫文件
- 对多语言站点，需额外传
--rules="region"等参数显式启用 WCAG 2.2 新规则，否则默认只跑 2.1 基线
在 webpack 构建流程中嵌入 axe-html-validator
把可访问性检查塞进构建环节，比人工跑命令更防遗漏。但 axe-html-validator 插件不是“加了就完事”，它默认只校验 index.html，而现代前端工程往往有上百个路由对应的 HTML 模板或 SSR 输出片段。
使用场景：你用 Webpack + HtmlWebpackPlugin 生成多个 HTML，但只看到首页的 a11y 报告，其他页面（如 /404.html、/privacy.html）完全没被扫描。
立即学习“前端免费学习笔记（深入）”；
- 配置时要遍历
HtmlWebpackPlugin.getHooks(compiler).afterEmit钩子，对每个产出的 HTML 文件单独调用axe.run() - 遇到内联 SVG 或
<script type="application/ld+json"></script>会误报「空链接」，需在插件选项中加rules: { "link-in-text-block": { enabled: false } } - CI 中建议设
failOnViolation: true，但别用默认阈值；例如允许最多 3 条color-contrast警告，避免因设计稿未定死而阻塞发布
VS Code 里实时高亮 aria-* 错误
编辑器侧的反馈延迟越低，修复成本越小。但单纯装 eslint-plugin-jsx-a11y 对纯 HTML 文件无效——它只处理 JSX，不解析 .html 后缀。
容易踩的坑：你在 index.html 里写了 <div role="button" onclick="...">，VS Code 却毫无提示，直到上线才被 axe 扫出来。
- 必须安装
HTMLHint插件，并在.htmlhintrc中启用attr-accessible-headings和attr-aria-role规则 -
role="button"必须配tabindex="0"和键盘事件（onkeydown），仅靠 HTMLHint 不会检查 JS 逻辑，得靠自定义 rule 调用acorn解析内联脚本 - 对 Vue/Svelte 模板，需配合
volar或svelte-check的 a11y 模式，否则aria-labelledby绑定到不存在的 ID 无法被提前捕获
用 Lighthouse CI 自动归档历史 a11y 分数
Lighthouse 的 a11y 分类分数（0–100）本身意义有限，真正有用的是趋势对比。但默认的 lighthouse-ci 配置只存最新一次结果，没法回答“上周的登录页为什么从 92 掉到 85？”
性能影响：每次跑完整 Lighthouse（含 performance、SEO）耗时 30–60 秒，若只为看 a11y，应关闭其他 category 并指定 --preset=desktop 避免移动端模拟拖慢 CI。
- 在
.lighthouserc.json中设"collect": { "url": ["http://localhost:3000/login"], "settings": { "onlyCategories": ["accessibility"] } } - 归档数据必须用
lhci server自建服务，SaaS 版（如lhci-canary）不保留原始审计项，只给汇总分 - 关键细节：Lighthouse 的 a11y 测试基于 axe-core 4.x，但部分企业还在用 3.x 规则集，版本不一致会导致同一份 HTML 在不同环境报出不同问题
最常被跳过的环节是跨框架一致性——Vue 的 v-if 和 React 的 {condition && <div>} 在 DOM 消失时，是否同步移除了关联的 <code>aria-owns？这类问题不会出现在单页 HTML 扫描里，必须结合真实用户流录制 Lighthouse。
