自研脚手架生态：无缝集成HTML代码质量防线的构想-html教程-PHP中文网

自研脚手架集成 html 质量检查需统一使用项目根目录 .htmlhintrc 配置，严格绑定 pre-commit 钩子与 ci 流程，确保规则生效、错误可追溯、失败即阻断，并按项目类型预置差异化规则。

自研脚手架生态：无缝集成html代码质量防线的构想

自研脚手架里集成 HTML 质量检查，不是“加个插件就完事”，而是得让 htmlhint 的执行时机、配置粒度、错误反馈路径都贴合你团队的真实提交和构建节奏——否则它很快就会被 npm run lint 里跳过的那行注释绕过去。

htmlhint 配置必须绑定到项目根目录的 .htmlhintrc，不能靠 --config 临时指定

很多人在脚手架里用 npx htmlhint src/**/*.html --config ./configs/htmlhint.json 启动检查，看似灵活，实则埋雷：CI 环境里路径可能错位；开发时本地改了配置但没 commit，导致本地通过、CI 失败；更麻烦的是，htmlhint 的 attr-lowercase 这类规则对自定义属性（如 data-xxx）默认不生效，除非配置里显式启用 attr-lowercase: { "except": ["data-*"] }。

正确做法是统一用项目根目录下的 .htmlhintrc，且必须包含：

"attr-lowercase": true —— 否则 React/Vue 模板里混写的 DATA-ID 或 ngIf 会漏检
"tag-pair": true —— 防止 <div><span></span></div> 这类嵌套错位在 SSR 渲染时出问题
"id-unique": true —— 动态生成的组件（如列表项）若复用相同 id，会影响无障碍读屏和 JS 查询

pre-commit 钩子里跑 htmlhint，但要排除 node_modules 和构建产物目录

把 htmlhint 塞进 pre-commit 是最有效的防线，但直接 npx htmlhint "**/*.html" 会扫描 dist/ 或 build/ 下的生成文件，既慢又无意义，还可能因压缩后 HTML 格式异常报错。

在 .pre-commit-config.yaml 中应这样写：

repos:
  - repo: local
    hooks:
      - id: htmlhint
        name: HTML code quality check
        entry: npx htmlhint
        types: [html]
        files: ^(src|public|templates)/.*\.html$
        pass_filenames: true

注意三点：

html-ppt-to-pdf

将使用 `

` 约定的 HTML 幻灯片转换为高保真、矢量文本 PDF（使用 Playwright + Chromium 原生 PDF 功能）。

下载

files 正则限定作用域，避免扫到 node_modules 或 CI 自动生成的报告页
types: [html] 依赖 pre-commit 的类型识别，比单纯靠扩展名更可靠
别用 args 传 --quiet——开发者需要看到具体哪一行、哪个规则失败，否则没人愿意修

CI 流程中 htmlhint 必须失败即中断，且输出 SARIF 格式供 GitHub Code Scanning 解析

GitHub Actions 里只写 npx htmlhint "**/*.html" || echo "done" 是自欺欺人。CI 的核心价值在于“阻断劣质代码进入主干”，所以必须让检查失败时整个 job 退出码非 0。

同时，原生 htmlhint 输出是纯文本，GitHub 的 Code Scanning 不认。得加 --format=sarif 并重定向到文件：

- name: Run HTMLHint (SARIF)
  run: |
    npx htmlhint . --format=sarif --output=htmlhint-results.sarif || exit 1
  shell: bash

后续再接 actions/upload-artifact 和 github/codeql-action/upload-sarif，才能让问题直接出现在 PR 的 “Code scanning alerts” tab 里。漏掉 || exit 1 或格式不对，等于白跑。

脚手架 CLI 初始化时，.htmlhintrc 应根据项目类型预置差异化规则

一个全栈项目和一个纯静态官网，HTML 质量关注点完全不同：前者要严控 script 标签位置（防阻塞渲染）、meta 编码声明；后者可能允许内联样式或省略 alt（图库类页面）。

脚手架初始化命令（如 create-myapp --template=ssr）应自动写入不同版本的 .htmlhintrc：

SSR 模板：启用 "script-placement": ["head", "body"] 和 "meta-charset-require": true
静态站点模板：放宽 "alt-require": false，但强制 "doctype-first": true
微前端子应用模板：禁用 "id-unique"（由主应用统一分配 ID），但加 "attr-no-duplication": true

硬编码一套通用规则，不如不做——团队很快就会在 // htmlhint-disable-line 上达成默契，然后集体绕过。