非前端开发者写html最常触发的5类htmlhint报错是alt-require、tag-pair、attr-lowercase、html-lang-require、title-require,根源在于忽视可访问性、语义规范与模板引擎特性导致的合规性缺失。

非前端开发者写HTML时最常触发的5类HTMLHint报错
非前端开发写HTML,往往不是语法错误,而是“合规性缺失”——浏览器能跑,但不符合可维护、可访问、可测试的基本要求。HTMLHint默认规则里,alt-require、tag-pair、attr-lowercase、html-lang-require、title-require这5条最容易被踩中。
比如服务端同学用Thymeleaf或JSP生成页面,习惯性省略<img>的alt属性,或把class写成Class,或漏掉——这些在本地调试完全无感,但一进CI就被HTMLHint拦住,还附带一句“Accessibility violation”。
-
alt-require:不是“可选”,是WCAG 2.1强制要求,搜索引擎和读屏器依赖它 -
tag-pair:自闭合标签如<img>不加/在XHTML模式下会出问题,Prettier格式化时也可能误判嵌套 -
attr-lowercase:大小写混用会让Prettier和HTMLHint规则冲突,导致保存后又报错 -
html-lang-require:影响SEO和语音朗读,但后端模板里常被忽略 -
title-require:很多脚手架生成的index.html自带,但动态模板(如FreeMarker)容易漏
如何让HTMLHint检查不变成“提交阻塞”
直接把HTMLHint加进CI的pre-commit钩子,对非前端同学等于设置了一道“认知门槛”——报错信息全是英文、没上下文、不指明哪行哪列。结果就是绕过检查、删配置、或硬加<!-- htmlhint disable -->注释。
真正可行的做法是分层介入:
如果你了解HTML,CSS和JavaScript,您已经拥有所需的工具开发Android应用程序。本动手本书展示了如何使用这些开源web标准设计和建造,可适应任何Android设备的应用程序 - 无需使用Java。您将学习如何创建一个在您选择的平台的Android友好的网络应用程序,然后转换与自由PhoneGap框架到一个原生的Android应用程序。了解为什么设备无关的移动应用是未来的潮流,并开始构建应用程序,提供更
- VS Code里装
HTMLHint插件 +Prettier插件,保存即修复基础格式(缩进、引号、空格),并高亮显示alt缺失等关键项 - 在
.htmlhintrc里关掉对非前端不友好的规则,比如attr-no-duplication(模板引擎可能动态拼接属性)、id-unique(服务端渲染常有循环生成ID) - 用
htmlhint --format=unix输出带行号的错误,配合lint-staged只检查本次提交的HTML文件,避免全量扫描拖慢 - 在团队文档里写清楚每条保留规则的“为什么”——例如“
alt-require: true是因为产品要求所有图片必须支持无障碍访问,上线前会被质检抽查”
Prettier + HTMLHint组合配置的三个易错点
很多人以为装了Prettier就不用HTMLHint,或者反过来。其实二者职责完全不同:Prettier管“怎么排版”,HTMLHint管“有没有漏关键语义”。但组合使用时,三个配置细节常被忽略:
-
.prettierrc里设"htmlWhitespaceSensitivity": "css",否则Prettier可能把<div> text </div>格式化成<div>text</div>,破坏文本可读性 -
.htmlhintrc里不要开attr-value-double-quotes,如果Prettier设了singleQuote: true,两者会互相打架 - Vue/React项目里,HTMLHint默认不识别
<template></template>或JSX中的HTML片段,需额外配"htmlhint": {"htmlhint": {"ext": [".html", ".vue", ".jsx"]}}(注意不同版本路径写法差异)
服务端同学写HTML时该关注的3个最小质量红线
不必强求写出“前端级”的HTML,但以下三点是跨角色协作的底线,踩中任意一条,前端同学接手时大概率要重写结构:
- 所有
<img>、<iframe></iframe>、<video></video>必须带alt或aria-label(哪怕写alt="") - 每个页面必须有且仅有一个
<h1></h1>,且不能是纯数字或无意义占位符(如<h1>Page</h1>) - 表单控件必须有
label关联(用for/id或嵌套),不能只靠placeholder说明意图
这些不是“最佳实践”,而是避免后续被前端拒收、被QA打回、被无障碍检测工具标红的硬性门槛。工具可以帮发现,但意识得从第一次写<img src="...">时就建立。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










