axe-core需在CI中通过Puppeteer扫描构建后HTML，而非静态文件；须等待readyState完成、聚焦高危规则、转换为Prometheus指标；生产环境用MutationObserver探针捕获动态退化；SSR需校验服务端HTML语义完整性。
用 axe-core + CI 流水线做可访问性健康度快照
纯 HTML 文件无法自我诊断，必须靠外部 JS 引擎驱动扫描。axe-core 是目前最稳定的开源可访问性检测引擎，它不依赖浏览器 UI，能嵌入 Node 环境或 Puppeteer 实例中运行，适合集成进 CI/CD 流程。
关键点在于：不是“监控 HTML”，而是“在每次构建后，用 axe-core 扫描生成的 HTML 页面”。
- 安装：
npm install axe-core（注意不是axe，后者是旧版 CLI 工具） - 搭配 Puppeteer 启动真实 Chromium 实例，避免 jsdom 对
aria-*属性、焦点管理等行为模拟不准的问题 - 扫描前必须等待
document.readyState === 'complete'，否则document.querySelector()可能返回null - 设置
runOnly: { type: 'rule', values: ['color-contrast', 'label-title-only', 'image-alt'] }可聚焦高频高危项，跳过低影响规则加速反馈
把可访问性检测结果接入 Prometheus + Grafana 做趋势监控
axe-core 本身只输出 JSON 报告，要变成可观测指标，得加一层转换逻辑——把每个规则的失败数、页面总数、严重等级映射为 Prometheus 的 Gauge 或 Counter。
常见错误现象：TypeError: Cannot read property 'length' of undefined，通常是因为某页面没加载出 body 就调用了 axe.run()，需加 try/catch 并上报 accessibility_scan_failure_total{page="/login",reason="timeout"} 这类带标签的指标。
立即学习“前端免费学习笔记（深入）”；
- 用
performance.getEntriesByType('navigation')记录首屏加载耗时，和可访问性失败率做交叉分析：慢页面是否更易漏掉alt？ - Grafana 面板里建议设两个关键阈值线：单页严重问题 ≥3 条标为警告，≥5 条标为异常；整站通过率连续 3 次低于 95% 触发告警
- 别直接暴露原始 axe 报告给 Prometheus，它含 DOM 节点快照，体积大且敏感；只上报聚合后的
violations_count和passing_rules_ratio
绕过静态 HTML 限制：用 MutationObserver 动态捕获运行时可访问性退化
CI 扫描只能覆盖构建时的快照，但真实用户操作可能触发新问题：比如点击按钮后动态插入的弹窗没加 aria-modal="true"，或懒加载图片未补 alt。
这时需要在生产 HTML 中注入轻量级探针脚本，监听 DOM 变化并按需触发局部 axe 检查。
- 脚本必须用
async加载，避免阻塞渲染；入口函数包裹在if ('MutationObserver' in window)判断里，兼容旧版 Safari - 监听范围限定在
document.body，忽略head和第三方 SDK 插入的 iframe 内容，防止误报 - 对每个新增节点，只检查其直接子树（
axe.run(node, { runOnly: [...] })），避免全页重扫拖慢主线程 - 上报字段精简为：
page、selector、ruleId、impact（critical/minor），不传helpUrl或修复示例
别忽略服务端渲染（SSR）场景下的可访问性盲区
当 HTML 由 Next.js、Nuxt 或 ASP.NET Core MVC 渲染时，服务端生成的初始 HTML 可能缺失语义结构，而客户端 hydration 后才补全——这会导致 axe 在服务端快照中漏检，但在浏览器中实际已存在缺陷。
最容易被忽略的一点：SSR 框架默认不会序列化 aria-live 区域或 role="application" 容器，这些在服务端不可见，但对屏幕阅读器至关重要。
- 验证方式：用 curl 获取原始 HTML，再用
axe-core的 Node 版本直接解析字符串，比对与浏览器端扫描结果的差异 - 修复路径：在 SSR 模板中显式写出
<div aria-live="polite"></div>，而不是靠 JS 初始化 - 若用 ASP.NET Core Health Check，可复用同一套探针逻辑，在
/health/accessibility端点返回当前首页的可访问性评分，供运维看板拉取
