github actions 工作流应监听 pull_request（types: [opened, synchronize, reopened]）用于预合并审查，及 push（仅限 main 或 production 分支）用于全量快照检查；避免 push 绑定通配符分支或遗漏 pr 类型，确保 html 质量审查精准高效。

GitHub Actions 工作流该监听哪些事件

HTML 项目通常不编译、不打包，但质量审查仍需在关键节点触发。最实用的组合是 pull_request + push，但必须区分用途：pull_request 用于预合并审查（聚焦变更部分），push 仅限 main 或 production 分支，用于全量快照检查。

常见错误是把 push 绑定到所有分支（如 **），导致每次 feature 分支提交都跑一遍 HTML 检查，浪费资源且反馈噪音大。另一个坑是忽略 pull_request 的 types：默认只响应 opened，但代码修改后重新推送（synchronize）或 PR 被重新打开（reopened）时，审查结果不会自动更新——必须显式声明：

• types: [opened, synchronize, reopened]

用什么工具检查 HTML 质量

纯 HTML 项目没有构建步骤，但仍有三类问题必须拦截：语法合法性（如标签嵌套错误）、可访问性（alt 缺失、ARIA 使用不当）、SEO 基础项（title、meta description）。推荐组合是 html-validate（可配置规则集） + axe-core CLI（专注 a11y）。

html-validate 比原生 tidy 更适合工程化：它支持 JSON 配置、可扩展规则、能输出标准格式报告。而 axe-core CLI 是唯一能在 CI 中直接跑完整可访问性扫描的轻量方案（无需启动浏览器）。不要用 W3C Validator API，它有调用频率限制且无本地缓存，CI 中容易超时失败。

示例关键步骤：

• run: npx html-validate --config .htmlvalidate.json src/**/*.html
• run: npx axe-cli --reporter=cli --output=axe-report.json src/**/*.html

如何让审查结果真正可见

只在 Actions 日志里打印错误行，等于没反馈。HTML 项目缺乏编译产物，没法像 JS 那样集成 ESLint 报告插件，所以必须靠 GitHub PR 评论主动触达开发者。

Git Repo Cleaner

审计并清理 Git 仓库。查找陈旧/已合并的分支、历史中的大文件、孤立标签、仓库膨胀，并生成清理脚本。使用时机...

下载

最简方案是用 actions/github-script 提取 html-validate 的 JSON 输出，按文件聚合错误，再调用 GitHub REST API 发评论。注意两个硬性条件：

• Workflow 必须声明 permissions: pull-requests: write，否则 API 调用会 403
• html-validate 输出必须加 --output-format=json 参数，否则无法结构化解析

别尝试用 reporter=github-pr-check 这类第三方 reporter——它们依赖 GitHub App 权限，在普通仓库 Action 中不可靠，且对 HTML 文件支持差。

为什么不能跳过本地验证直接上 CI

CI 环境里跑 HTML 审查慢（尤其带 axe 扫描），且失败后调试成本高。必须在本地加一层守门员：VS Code 用户装 HTMLHint 或 Auto Close Tag 插件；命令行用户加 pre-commit 钩子。

一个典型 .pre-commit-config.yaml 配置：

• repos:
• - repo: https://github.com/html-validate/pre-commit
• rev: v7.12.0
• hooks:
• - id: html-validate

这样 commit 前就拦截 80% 的基础语法错误，CI 只需专注 a11y 和深度规则。否则每次 PR 都因 <img> missing alt 失败，团队会很快无视所有审查结果。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！