HTML解析引擎不校验合法性，仅自动纠错；合法性的准确判断需依赖W3C Validator等外部工具，其报Error即违反HTML5规范，必须修复。

HTML解析引擎本身不“校验”合法性，它只按规范尽力解析并自动纠错；真要判断文档是否合法，必须绕过它的容错行为，用外部手段交叉验证。

浏览器 Elements 面板里出现灰色/斜体节点就是非法结构的铁证

Chrome、Edge 等基于 Blink/WebKit 的浏览器在解析 HTML 时，会静默修正明显错误，比如把 <p></p> <div>xxx</div>

中的 <div> 移出 <code><p></p>。这些被修正的节点在 Elements 面板中会显示为灰色、斜体或带删除线——不是样式问题，是解析器打的“违法标记”。

常见触发场景：

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

立即学习“前端免费学习笔记（深入）”；

• <p><section>text</section></p> → <section></section> 被提到 <p></p> 外，DOM 树断裂
• <script>console.log(1)</script>（没加 defer 或 type="module"）→ 节点标灰，Console 可能提示 “HTML validation warning”（需开启 DevTools Settings → Console → Verbose）
• <table><div></div></table> → <div> 被提到 <code><table> 外，甚至可能上移到 <code> 顶层

  注意：Elements 默认折叠空文本节点和注释，手动展开才能看清嵌套是否连贯；右键节点 → “Break on” → “Attribute modifications”，可捕获 JS 动态破坏结构的行为。

  W3C Validator 报 Error 就说明违反 HTML5 规范，不是“看着能用就不管”

  W3C Markup Validation Service 不执行任何纠错，它只比对原始字符串与 HTML5 内容模型。报 Error 意味着结构已失效，不是警告，必须修复。

  典型错误及含义：

  • Stray end tag：多写了闭合标签，或父标签提前闭合，导致后续内容“漂浮”在根节点下
  • Element div is not allowed as child of element p：<p></p> 只允许短语级内容（phrasing content），<div>、<code><section></section>、<h2></h2> 等块级元素禁止嵌套其中
  • Bad value X for attribute Y：比如 rel="loading" 应为标准值 preload / prefetch；status="pending" 应写成 data-status="pending"

  粘贴代码时务必包含完整 <!DOCTYPE html> 至 </html>，否则报 “document has no root element”。含内联 <script> 时，若内容里有未转义的 < 或 &，会被截断，报 “unexpected token”——这不是标签问题，是字符转义漏了。

  document.documentElement 为 null 说明 HTML 根本没进入解析流程

  这比结构错误更底层：不是“解析错了”，而是“压根没开始解析”。常见原因不是代码写错，而是加载链路异常。

  排查优先级：

  • 检查 Network 面板响应头中 Content-Type 是否为 text/html;charset=utf-8；若为 text/plain，浏览器直接当纯文本处理
  • 确认响应体非空：SSR 渲染失败、CDN 返回 204、构建产物缺失 <!DOCTYPE html> 都会导致空响应
  • 本地用 file:// 协议打开时，部分浏览器拒绝解析，且 W3C Validator 也因缺失 HTTP 头而失效
  • 前端用 fetch 拿到 HTML 字符串后，若没调用 response.text() 就直接丢给 DOMParser，也会失败

  执行 document.documentElement 返回 null 是最硬信号，此时所有 DOM 操作都无意义，先修通加载路径再谈结构。

  CI 流水线必须用 parse5 + html-validate 离线校验，不能调 W3C API

  W3C 在线服务有速率限制、网络依赖、且不支持 file://，CI 中无法稳定使用。Node.js 环境应采用离线方案：parse5 提供标准兼容的 HTML 解析器，html-validate 基于它做规则校验。

  关键配置要点：

  • 禁用宽松规则（如 attr-bans），强制启用 require-lang-attribute、valid-href、no-inline-style
  • <template> 标签内容跳过校验——它本就不参与主 DOM 解析，W3C 也忽略
  • 内联 <script> 或 <style> 含 < 或 & 时，需前置过滤转义，否则校验器直接截断报错
  • CI 脚本示例：npx html-validate --config .htmlvalidate.json src/**/*.html，退出码非 0 即中断构建

  特别注意：data-test-id 报 “unknown attribute” 只有一个原因：缺 <!DOCTYPE html>。没有 doctype，文档进入 Quirks Mode，所有 data- 属性都被视为非法。别删它，去补 doctype。