html-validate适合静态HTML源码扫描，axe-core必须运行在真实DOM环境；前者通过配置文件控制规则粒度，后者需搭配Playwright等工具执行可访问性断言。
HTML静态扫描该用 html-validate 还是 axe-core？
别纠结“哪个更好”，先看你要解决什么问题：html-validate适合扫源码文件（如 src/**/*.html），能精确控制规则粒度；axe-core必须跑在真实 DOM 环境里，适合 Cypress 或 Playwright 测试中做可访问性断言，但没法直接读取未渲染的 HTML 文件。
常见错误现象：把 axe-core 当成静态 linter 用，写个 npx axe-core index.html 报错或静默退出——它根本没这个 CLI 接口。
-
html-validate配置靠.htmlvalidate.json，支持"attr-req-alt": "error"这类硬性开关 -
axe-core必须搭配 Puppeteer/Playwright，例如用npx axe-playwright --ci src/index.html - 如果项目混用 Vue/React 模板，可加
eslint-plugin-html，但它只处理 JS 字符串里的 HTML 片段，不覆盖纯 HTML 页面
GitHub Actions 里怎么写 HTML 扫描 job 才不踩坑？
关键不是“能不能跑起来”，而是“失败时是否真阻断”和“报错定位到哪一行”。默认配置下，很多扫描命令输出模糊、路径错乱、甚至被 node_modules 拖垮。
- 路径必须写具体，比如
src/templates/**/*.html，绝不能用**/*.html—— 否则会扫描node_modules和.git，CI 超时或误报 -
html-validate加--max-warnings 0，否则警告不阻断，等于白跑 -
htmlhint默认不带行号，必须加--format=compact参数才能准确定位 - 所有 job 前加
npm ci，避免依赖版本漂移导致规则行为变化 - job 不要依赖
build步骤，应独立设置needs: checkout，防止构建失败导致扫描跳过
如何动态忽略特定页面或规则？
不是所有 HTML 都适用同一套 WCAG 规则。微前端子应用、iframe 嵌入页、服务端渲染片段模板，硬塞 <title> 或 lang 属性反而破坏语义。
立即学习“前端免费学习笔记（深入）”；
- 用
.htmlvalidate.json的ignore字段按 glob 忽略路径："ignore": ["src/micro-fe/**/*.html"] - 用
rules覆盖单条规则："document-title-missing": "off" - 千万别用 HTML 注释关规则（如
<!-- html-validate-disable document-title-missing -->），CI 环境不识别这种行内指令 - 多语言站点才需
attr-req-lang，内部管理页开启它只会增加噪音
为什么扫描总在 CI 里报错，本地却正常？
根源通常是环境不一致：本地用全局安装的工具版本，CI 用 npx 调用，而 npx 默认找最新版 —— 新版规则更严，旧版可能已废弃某些检查项。
- 固定工具版本：改用
npx html-validate@5.12.0 --config .htmlvalidate.json ... - 确保 CI 中
.htmlvalidate.json与本地完全一致（Git 跟踪、不忽略） - 检查路径是否含 Windows 风格反斜杠（
\），CI 运行在 Linux，路径解析会失败 - 若用
prettier --parser html格式化后再扫描，注意它不修复嵌套错误（如<div><p></div></p>），这类问题得靠html-validate的valid-elements规则捕获
真正难的不是让工具跑起来，而是判断哪些规则对当前业务场景是“必须失败”的红线——这需要和产品、无障碍团队对齐，而不是照搬配置模板。
