推荐使用HTMLHint（轻量可配置）、axe-core（专注可访问性）和prettier（统一格式）组合工具；HTMLHint需启用attr-lowercase、attr-no-duplication等核心规则，axe-core须配合Puppeteer动态执行，prettier需指定--parser html参数，GitHub Actions中应添加--format=compact和cd $GITHUB_WORKSPACE确保准确定位与路径一致。
HTML代码质量检查该用什么工具
HTML本身没有编译环节，但语法错误、语义不规范、可访问性缺陷会直接影响渲染和SEO。直接靠人眼 review 几乎不可靠，必须引入静态分析工具。推荐组合使用：HTMLHint（轻量、可配置规则）、axe-core（专注可访问性）、prettier（统一格式，避免团队风格争议）。
注意：HTMLHint默认规则较宽松，容易漏掉常见问题，比如缺少alt属性、重复id、未闭合标签等，必须手动启用对应规则；axe-core需配合无头浏览器（如Puppeteer）运行，不能只靠静态扫描——纯静态分析会误报aria-*属性缺失，而动态执行才能确认DOM是否真实渲染。
-
HTMLHint建议启用attr-lowercase、attr-no-duplication、head-script-disabled等核心规则 -
axe-core必须在CI中启动一个最小化浏览器环境，否则document.querySelector类检测全部失效 -
prettier对HTML支持有限，仅处理缩进和空白，别指望它修复<div><p></div></p>这类嵌套错误
GitHub Actions里怎么写HTML质量检查步骤
GitHub Actions是目前最轻量、免运维的HTML CI方案，适合静态站点。关键不是“能不能跑”，而是“失败时能否准确定位到哪一行”。HTMLHint默认输出不带行号，必须加--format=compact参数；axe-core报告默认是JSON，需用axe-reporter转成可读文本并设failOnViolation: true。
示例片段（放入.github/workflows/html-check.yml）：
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- name: HTML lint
run: |
npm ci
npx htmlhint --format=compact src/**/*.html
<ul><li>name: Accessibility check
run: |
npx axe-playwright --ci src/index.html注意：不要把src/**/*.html写成**/*.html——CI会扫描node_modules和.git目录，导致超时或误报；也不要省略npm ci，htmlhint依赖版本不一致时规则行为可能变化。
为什么HTML检查总在CI里通过，本地却报错
根本原因通常是路径解析差异。CI环境默认工作目录是仓库根，而本地开发常在子目录下运行命令；更隐蔽的是Node.js模块解析机制：某些插件（如htmlhint-loader）会读取package.json里的htmlhintConfig字段，但CI里npm ci可能跳过devDependencies安装，导致配置未加载。
- 本地运行
npx htmlhint src/index.html时，实际读取的是./.htmlhintrc；CI里若没显式指定--config，会 fallback 到内置默认规则 -
prettier对HTML的格式化结果受parser选项影响，CI脚本里必须明确写prettier --parser html，否则可能按JS解析导致崩溃 - 所有HTML检查命令前加
cd $GITHUB_WORKSPACE确保路径一致，尤其当项目结构是docs/或public/时
HTML CI流水线要不要加自动化测试
纯静态HTML页面不需要单元测试，但需要验证“链接是否404”“资源路径是否正确”“关键元素是否渲染”。这类检查本质是端到端验证，不是传统意义上的测试，但能拦截90%的手动部署失误。
推荐用linkinator扫死链（支持并发、忽略特定域名）、playwright断言关键DOM存在（如document.querySelector('header nav')），而不是写Selenium脚本——后者启动慢、不稳定，CI里容易超时。
-
linkinator命令示例：npx linkinator ./dist --ignore-url='https://example.com' --timeout=5000 - Playwright脚本必须用
page.goto('file://'+path.resolve('./dist/index.html'))而非http://localhost，避免额外起服务增加复杂度 - 别把HTML CI和构建流程耦合——Webpack打包后的HTML才需要做链接检查，源码HTML做语法检查就够了
真正容易被忽略的点是：HTML质量门禁必须阻断merge，而不是只发报告。GitHub Actions里要确保on: [pull_request]且所有检查步骤都设if: github.event_name == 'pull_request'，否则PR页面看不到状态检查按钮。
