混合容器中HTML结构易“看似正常实则违规”，因WebView等自动补全缺失标签、容忍非法嵌套，导致DOM断裂、语义丢失、SEO降权；需用HTMLHint启用doctype-first、tag-pair、html-lang-require等规则，并校验构建产物而非源码。
为什么混合容器里 HTML 结构容易“看起来正常却实际违规”
WebView、Flutter Web、React Native WebView 或 Capacitor 等混合容器，常会忽略或弱化 HTML 解析的严格性——比如自动补全缺失的 <html>、<head>、<body>，甚至容忍未闭合标签。这导致开发者误以为结构没问题，但上线后在 Safari、旧版 Android WebView 或屏幕阅读器中出现 DOM 断裂、语义丢失、SEO 降权等问题。
HTMLHint 在混合容器项目中必须启用的核心规则
默认规则集对混合环境不够敏感，需显式打开以下几条：
-
doctype-first：强制<!DOCTYPE html>出现在第一行，避免容器 fallback 到怪异模式（Quirks Mode） -
tag-pair：检查所有可闭合标签是否成对，尤其注意<div>嵌套在<p>内这类非法嵌套（混合容器常不报错但破坏语义） -
html-lang-require：确保<html lang="zh-CN">存在，否则 TTS 引擎和部分 WebView 的字体渲染可能异常 -
meta-charset-require：必须有<meta charset="UTF-8">，否则中文乱码在低版本 WebView 中高频出现 -
attr-lowercase和tagname-lowercase：大小写混用在 iOS WKWebView 中偶发解析失败（尤其自定义属性名）
CI/CD 中检测 HTML 结构时的路径陷阱
混合项目常把 HTML 放在非标准位置：如 src/assets/html/、public/webview/，甚至由 JS 动态拼接生成。直接运行 npx htmlhint "**/*.html" 会漏掉这些文件。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 确认构建产物目录（如
dist/webview/）是否包含最终注入容器的 HTML，并对该目录运行检查 - 若 HTML 由模板字符串拼接（如 Vue SFC 的
<template>或 React JSX），需先用html-loader或html-webpack-plugin提取为真实文件再校验 - Capacitor 项目中，
capacitor.config.json的webDir字段指向的目录才是真实入口，别只扫src/ - Flutter Web 项目中，
web/index.html是唯一需校验的 HTML，其余.dart生成的 DOM 不在此列
W3C Validator 与混合容器验证结果不一致怎么办
W3C Validator 报错“Document is empty”或“Missing DOCTYPE”，但你在 WebView 里能正常显示——这通常是因为你校验的是 JS 渲染前的骨架 HTML（比如只有 <div id="root"></div>），而 W3C 只检查静态结构，不执行 JS。
关键判断点：
- 如果 HTML 是纯静态资源（如离线帮助页、欢迎页），必须通过 W3C 验证，且无 error
- 如果是单页应用（SPA）的入口 HTML，只需保证基础结构合规（
<html>、<head>、<body>、<meta charset>、<title>），动态内容交给HTMLHint+ 运行时 axe 检查 - 警惕“W3C 通过但容器崩溃”：常见于使用了
<picture>+srcset但未提供 fallback<img src>，某些低端 WebView 会直接丢弃整个节点
真正难缠的不是语法错误，而是那些浏览器不报错、但语义断裂或可访问性失效的结构问题——比如把 <button> 写成 <div onclick>，HTMLHint 能抓 onclick，但不会提醒你缺 role，这时候得靠 axe 配合。
