必须在文件最开头严格写，前面不能有空格、bom、注释或空行；内不可嵌套等块级元素，需调整html结构。
W3C校验器报“missing DOCTYPE”就卡住？第一行必须严格写
绝大多数人第一次校验失败，不是代码写错了，而是没出现在文件最开头——前面不能有空格、BOM头、注释、XML声明，甚至不能有一行空行。浏览器能容错渲染，但校验器直接标红。
常见错误包括：
- 用旧式声明如
，校验器会按 HTML5 规则解析，导致误报 - 构建工具（Vite/Webpack）注入了模板变量或注释到 index.html 开头，比如
<!-- built at 2026-05-08 -->，必须删掉 - 编辑器保存时加了 UTF-8 BOM（尤其 Windows 记事本），校验器读到
 就判定非法
校验器说“Element div is not allowed here”，本质是违反 HTML 内容模型
这不是浏览器兼容问题，而是语义结构错误。典型场景：<p></p>里写了<div>、<code><section></section>或<h2></h2>，因为<p></p>只允许短语级内容（phrasing content），块级元素不允许嵌套其中。
解决方式不是加 CSS hack 或强行忽略，而是改结构：
- 把
<p></p> <div>...</div>改成<div><p>...</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill8272" title="anything-to-html"><img src="https://img.php.cn/upload/skill/000/000/081/179195588450431.jpg" alt="anything-to-html" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill8272" title="anything-to-html" class="overflowclass">anything-to-html</a> <p class="overflowclass">将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。</p> </div> <a rel="nofollow" href="/xiazai/skill8272" title="anything-to-html" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div></div>或直接用<div> 替代 <code><p></p> -
<script></script>放在里，必须加defer或显式声明type="module"，否则校验器认为它可能阻塞解析 - 自定义标签如
<my-button></my-button>未注册时，校验器按未知元素处理，报错“Element my-button is not allowed”——这属于预期行为，上线前确保已调用customElements.define() - 粘贴完整源码：含
、<code>、、，且不含任何模板语法（如{{ title }}、v-if） - 上传构建产物：用
npx serve -s dist启本地服务后，填http://localhost:5000；或直接上传dist/index.html文件 - 验证已部署页面：仅适用于公开可访问的 URL，若页面返回 403、被 CSP 拦截或 robots.txt 禁止爬取，会显示 “Unable to retrieve document”
-
v-if、@click、x-data→ 报 “Attribute … not allowed on element” -
{{ msg }}→ 报 “character ‘{’ is not allowed” -
<template></template>里的内容若未被编译，校验器会当作普通元素检查，可能报嵌套错误
本地 file:// 路径无法提交？校验器只认 HTTP(S) 响应体
W3C 校验器不支持 file:// 协议，也不读取相对路径的 CSS/JS。它只校验你提交的纯 HTML 文本本身。所以直接双击打开 HTML 文件再拖拽进校验器，必然失败。
正确做法只有三种：
为什么 Vue/React 模板总报错？校验器只认最终 HTML，不认框架语法
校验器不是运行时环境，它不会执行 JS、不解析 SFC、不识别指令。所有框架特有语法都是“非法字符”或“非法属性”：
关键判断点：校验对象必须是构建后的静态 HTML（如 Vite 的 dist/index.html），而不是 src/index.html 或开发服务器实时生成的页面。框架指令类报错不用修源码，但得确认构建流程是否干净输出标准 HTML。
最容易被忽略的是：校验通过 ≠ 页面可用。它不查 ARIA 属性拼错、DOM 动态插入的结构、图片 404、preload 失效或语义合理性——这些得靠 Lighthouse、axe 或手动测试补位。
