静态页面可访问性自动化检测须在生成后、部署前用axe-core注入扫描，而非依赖生成器插件；需结合htmlhint查源码、axe-core查渲染结果，通过playwright等加载file://协议页面并显式配置shadowdom/iframe支持，确保字体就绪、仅断言violations。
静态页面生成器里怎么加可访问性自动化检测
不能只靠生成器本身——它产出的是 HTML 文件，而可访问性问题藏在语义、ARIA、颜色对比、键盘流等运行时表现里。真正有效的自动化，得在生成后、部署前插入检测环节。
常见错误现象：用 hugo 或 jekyll 生成一堆 .html 文件，本地打开看着正常，上线后屏幕阅读器读不出导航、色弱用户看不清文字，但没人报错。
- 必须把
axe-core注入到生成后的页面中跑一次扫描（比如用 Playwright 加载每个 HTML 文件） - 别依赖生成器插件自带的“a11y 检查”——多数只是简单校验
alt是否存在，漏掉aria-live缺失、焦点管理失效等关键项 - 若生成器支持自定义 build hook（如 Hugo 的
build命令后钩子），可在该阶段调用axe.run()批量扫描输出目录下的所有 HTML - 注意路径处理：静态文件无服务端，
page.goto('file:///path/to/index.html')在 Playwright 中需启用--allow-file-access-from-files标志，否则跨域限制会阻断axe-core注入
为什么 axe-core 比 lighthouse 更适合静态页面 CI 检测
因为 lighthouse 需要启动 Chromium 实例并模拟完整加载流程，而静态页面没有 JS bundle、没路由、没 hydration，lighthouse 容易误判“首屏内容为空”或因资源路径错误直接失败；axe-core 只关心 DOM 结构和计算样式，轻量、稳定、可复现。
-
axe.run()返回结构化违规列表，可直接用expect(results.violations).toHaveLength(0)断言，CI 失败时精准定位到violation.nodes[0].target（如['#main-nav > ul > li:nth-child(2)']） - lighthouse 的
lhci autorun默认不失败，必须配assertions，且对单页 HTML 支持弱——它默认期望一个可路由的 Web server，不是file://协议 - axe-core 支持离线模式：无需网络、不依赖远程规则集，
require('axe-core')后直接调用，适合纯静态 CI 环境（如 GitHub Actions 的 ubuntu-latest + node） - 性能影响小：扫描 50 个 HTML 页面，axe-core 耗时通常在 2–3 秒内；lighthouse 单页平均耗时 8–12 秒，还容易因 timeout 报错
HTMLHint 和 axe-core 在静态生成流程里怎么分工
HTMLHint 查源码，axe-core 查渲染结果——两者缺一不可，但顺序不能反。
- HTMLHint 在生成前介入：检查模板中是否漏写
alt、for/id不匹配、role拼错（如roel="button"），靠.htmlhintrc配置"alt-require": true等规则 - axe-core 在生成后介入：能发现模板里没问题、但 JS 插入的动态内容没补
aria-label，或 CSS 覆盖导致color-contrast不达标（HTMLHint 看不到 computed style） - 容易踩的坑：把 axe-core 放进模板里用
<script src="axe.min.js"></script>——这会让最终页面多出 100KB 脚本，且无法在 CI 中断构建；正确做法是仅在测试环境注入，不打包进生产 HTML - 兼容性注意：某些静态生成器（如 Astro）默认移除未使用的
script标签，若你把 axe 检测逻辑写在页面内，可能被自动剔除
静态页面自动化检测最容易被忽略的三个点
不是工具不会跑，而是环境没对齐、上下文没覆盖、失败没拦截。
- 字体未加载完成就扫：静态页面常引用 Google Fonts，
getComputedStyle取到的是 fallback 字体字号/颜色，导致color-contrast误报；加await page.waitForFunction(() => document.fonts.check('16px "Inter"'))确保字体就绪 - 忽略
iframe内容：生成器嵌了第三方地图或视频，其内部 DOM 不受 axe 控制，但 WCAG 要求整个页面可访问；需单独配置include: [['iframe'] ]并用frameSelector显式指定可扫描的 iframe - 没设
resultType: 'violations'：axe 默认返回passes、incomplete、violations三类，CI 只应关注violations；漏设会导致results.violations.length === 0判断失效
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
