PHP小码农

Appearance

HTMLLint 验证 ​

HTMLLint 是对 HTML 代码进行静态分析和质量检查的工具集合。通过自动化验证，可以确保 HTML 代码符合规范、避免常见错误、提升代码质量。本节将介绍 W3C Validator、HTMLHint 配置方法、以及如何将 HTML 验证集成到 CI/CD 流程中。

前置知识

阅读本节前，建议先了解：注释规范

为什么需要 HTML 验证 ​

  • 发现语法错误：如未闭合标签、重复 id、无效属性等
  • 确保标准合规：验证是否符合 HTML5 规范
  • 提升代码质量：强制执行编码规范
  • 自动化检查：减少人工 code review 的工作量
  • CI/CD 集成：在代码合并前自动检查

W3C Validator ​

在线验证 ​

工具地址说明
W3C Markup Validation Servicevalidator.w3.org官方在线验证工具
W3C Unicornvalidator.w3.org/unicorn统一验证器

使用方法 ​

  1. 打开 W3C Validator
  2. 选择验证方式：
    • URL 验证：输入网页地址
    • 文件上传：上传 HTML 文件
    • 直接输入：粘贴 HTML 代码
  3. 点击 "Check" 按钮
  4. 查看验证结果

常见错误 ​

错误类型示例修复方法
重复 id<div id="main"> 出现多次确保每个 id 唯一
未闭合标签<p>文本添加闭合标签 </p>
无效属性<div class="">（空值）移除或提供有效值
嵌套错误<p><div></div></p>修复嵌套关系
缺少 alt<img src="img.jpg">添加 alt 属性
过时属性<font color="red">使用 CSS 替代

HTMLHint ​

HTMLHint 是一个可配置的 HTML 代码检查工具。

安装 ​

bash
# 全局安装
npm install -g htmlhint

# 项目安装
npm install --save-dev htmlhint

基本使用 ​

bash
# 检查单个文件
htmlhint index.html

# 检查多个文件
htmlhint *.html

# 检查目录
htmlhint src/**/*.html

配置文件 ​

在项目根目录创建 .htmlhintrc 文件：

json
{
  "tagname-lowercase": true,
  "attr-lowercase": true,
  "attr-value-double-quotes": true,
  "doctype-first": true,
  "tag-pair": true,
  "spec-char-escape": true,
  "id-unique": true,
  "src-not-empty": true,
  "attr-no-duplication": true,
  "title-require": true,
  "alt-require": true,
  "doctype-html5": true,
  "attr-spacing": false,
  "id-class-value": "underline",
  "style-disabled": false,
  "inline-styling": false,
  "inline-script-disabled": false,
  "space-tab-mixed-disabled": "space",
  "indent-spaces": 2,
  "indent-width": 2
}

规则说明 ​

规则说明默认值
tagname-lowercase标签名使用小写true
attr-lowercase属性名使用小写true
attr-value-double-quotes属性值使用双引号true
doctype-firstDOCTYPE 在文件第一行true
tag-pair标签必须成对true
id-uniqueid 必须唯一true
src-not-emptysrc 属性不能为空true
alt-requireimg 必须有 alttrue
title-requirehead 中必须有 titletrue
indent-spaces缩进使用指定空格数2

自定义规则 ​

json
{
  "tagname-lowercase": true,
  "attr-lowercase": true,
  "id-unique": true,
  "alt-require": true,
  "custom-rules": {
    "no-inline-styles": {
      "message": "不要使用内联样式",
      "test": function(node) {
        if (node.attribs && node.attribs.style) {
          return { message: "发现内联样式: " + node.attribs.style };
        }
      }
    }
  }
}

VS Code 集成 ​

HTMLHint 扩展 ​

bash
# 安装 VS Code 扩展
code --install-extension htmlhint.vscode-htmlhint

VS Code settings.json ​

json
{
  "htmlhint.enable": true,
  "htmlhint.options": {
    "tagname-lowercase": true,
    "attr-lowercase": true,
    "attr-value-double-quotes": true,
    "doctype-first": true,
    "tag-pair": true,
    "id-unique": true,
    "src-not-empty": true,
    "alt-require": true,
    "title-require": true
  }
}

CI/CD 集成 ​

GitHub Actions ​

yaml
# .github/workflows/html-lint.yml
name: HTML Lint

on: [push, pull_request]

jobs:
  htmlhint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g htmlhint
      - run: htmlhint "**/*.html"

npm scripts ​

json
{
  "scripts": {
    "lint:html": "htmlhint \"src/**/*.html\" --config .htmlhintrc",
    "lint:html:fix": "htmlhint \"src/**/*.html\" --config .htmlhintrc --format json > lint-report.json",
    "precommit": "npm run lint:html"
  }
}

Git Hooks（husky） ​

json
{
  "devDependencies": {
    "husky": "^9.0.0",
    "htmlhint": "^1.1.0"
  },
  "scripts": {
    "prepare": "husky",
    "lint:html": "htmlhint \"**/*.html\""
  }
}
bash
# .husky/pre-commit
#!/bin/sh
npm run lint:html

lint-staged 配置 ​

json
{
  "devDependencies": {
    "lint-staged": "^15.0.0"
  },
  "lint-staged": {
    "*.html": ["htmlhint --config .htmlhintrc"]
  }
}

验证报告示例 ​

src/index.html
  L5:10  attribute "class" is duplicated  - attr-no-duplication
  L12:5  tag "img" must have attribute "alt" - alt-require
  L25:3  id "main" is duplicated  - id-unique

src/about.html
  L1:1  DOCTYPE declaration is missing  - doctype-first
  L3:1  tag "head" is not closed  - tag-pair

3 files checked, 5 errors found.

注意事项 ​

  1. 验证 ≠ 无障碍检查：HTML 验证检查语法，不检查无障碍问题
  2. 配置要合理：不要启用所有规则，选择适合项目的规则
  3. 忽略第三方代码：使用 .htmlhintignore 忽略不需要检查的文件
  4. 结合其他工具：同时使用 axe-core 检查无障碍、Lighthouse 检查性能
  5. 修复而非忽略：尽量修复验证错误而非直接忽略

最佳实践 ​

  • 在项目中配置 HTMLHint 规则文件
  • 将 HTML 验证集成到 CI/CD 流程
  • 使用 husky 和 lint-staged 在提交前检查
  • 定期更新验证规则以适应项目需求
  • 将验证错误视为构建失败
  • 同时进行无障碍检查（axe-core）和性能检查（Lighthouse）

下一节

继续学习：HTML 结构与 SEO

参考链接 ​