ci阶段必须用axe-core在真实dom环境检测可访问性、htmlhint查静态语义，二者互补不可替代；需启动服务、等待hydration完成、显式断言失败、统一ci环境以避免渲染偏差。
CI 阶段做 HTML 可访问性与语义化体检，不能靠人工肉眼检查，必须用工具自动拦截问题；但仅运行 axe-core 或 htmlhint 不够——它们检测维度不同、触发时机不同、失败逻辑也不同，混用不配规则就等于没检。
为什么 axe-core 必须在真实 DOM 环境里跑
axe-core 检测的是运行时可访问性状态：ARIA 属性是否生效、焦点顺序是否合理、屏幕阅读器实际读出的内容是否匹配语义。它依赖 JavaScript 渲染后的 DOM，静态扫描根本无效。
- 直接对
.html文件跑axe-core会报错或返回空结果——它需要一个可交互的页面环境 - CI 中必须先启动服务（如
npx serve -s dist -p 3000），再用 Puppeteer 或 Cypress 加载http://localhost:3000后注入axe.run() - 常见失真：React/Vue 页面未等 hydration 完成就执行检测，
document.body.innerHTML还是空 div，导致漏报aria-*缺失或role错误 - 建议加等待逻辑，例如 Puppeteer 中：
await page.waitForFunction(() => document.querySelector('#root')?.children.length > 0)
HTMLHint 只能查静态结构，别让它背 axe 的锅
htmlhint 是纯文本解析器，它只认标签拼写、属性存在性、嵌套合法性，不关心 JS 渲染后 DOM 是否可访问。两者互补，但不能互相替代。
- 它能抓到
<img>缺alt、<button></button>没type、<section></section>被塞进<p></p>里——这些是语义化硬伤 - 但它完全无视
aria-hidden="true"是否误标了关键内容、tabindex="0"是否加在非交互元素上——这些得靠axe-core - 配置里必须显式启用语义规则，比如
"tag-pair": true、"id-unique": true、"alt-require": true，默认配置可能关掉部分检查 - CI 中命令别写成
npx htmlhint src/*.html——要覆盖所有产出 HTML：npx htmlhint dist/**/*.html
CI 流水线里断言失败必须显式控制
工具跑完不等于 CI 失败。htmlhint 默认遇到错误就 exit code 1，但 axe-core 的 CLI 封装（如 axe-cli）默认只输出 JSON，不终止流程——你得自己判断并退出。
-
axe-cli http://localhost:3000 --save --report=html生成报告但不管分数，哪怕可访问性得分为 0，CI 依然绿 - 必须加脚本解析输出：提取
violations.length或score字段，if [ $score -lt 90 ]; then exit 1; fi - GitHub Actions 中避免用
|| echo "done"吞掉错误码——这会让失败静默通过 - 若用 Cypress +
cypress-axe，需在afterEach里调用cy.checkA11y({ includedImpacts: ['critical', 'serious'] })，否则低优先级问题不会中断测试
本地高分 ≠ CI 高分，环境差异是最大盲区
本地跑 axe 得分 98，CI 里掉到 62，90% 是环境导致的渲染偏差，不是代码倒退。
- CI 容器里 Chrome 版本偏低（如 Chromium 115），不支持某些 ARIA 1.2 属性，
role="searchbox"直接被忽略，检测结果失真 - 没设
--disable-gpu --no-sandbox，容器内 Chrome 渲染异常，document.body.offsetHeight === 0导致 axe 提前退出 - 静态资源路径错误：CI 构建后
index.html引用/assets/main.js，但服务没配 history fallback，加载失败 → DOM 不完整 → axe 检出大量“缺失标签”误报 - 解决方法：CI 中统一用 Node 20+、Chromium 最新版镜像；服务启动后加健康检查（
curl -f http://localhost:3000/health）再跑检测
真正卡住可访问性上线的，从来不是工具没跑，而是没人看 report 里具体哪条 violation 被忽略、也没人确认 CI 环境和用户真实环境是否一致——这两点比选什么工具重要得多。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
