多端html结构“走样”根本原因是不同端解析器对空格、bom、引号、嵌套容忍度不一，需统一pnpm workspace共享模板+html-validate校验+语义标签契约+严格lint阻断。
为什么多端发布时HTML结构总在小程序/WebView/CDN里“走样”
根本不是模板写错了，而是同一份 HTML 在不同端被不同工具链解析时，对空格、BOM、属性引号、标签嵌套的容忍度不一致。比如：Webpack HTML 插件注入 <title></title> 前悄悄加空行，导致 不在首行；<code>iOS WKWebView 把未加引号的 class=header 截断为 class=header 后跟空格；安卓 X5 内核 直接忽略这种写法——结果是同一份代码，在 iOS 上正常，在安卓上丢失样式或 JS 无法定位元素。
必须是文件绝对首字符，前面不能有 BOM、空格、注释-
lang属性值必须严格符合BCP 47（如zh-CN），不能用zh或cn - 布尔属性（如
disabled）统一省略值，写成disabled而非disabled="disabled"，避免 SSR/hydrate 不一致 -
<main></main>全局只能出现一次，且不能嵌套在<header></header>、<footer></footer>或<nav></nav>内
如何让公共 HTML 模板在多仓库中不“发散”
靠复制粘贴、手动 npm 发布、Git 子模块同步模板，三个月内必出问题：有的项目用了新版 <button></button> 语义按钮，有的还在用 <div role="button">；有的漏了 <code>alt，有的写了但值为空字符串；更隐蔽的是，各项目 prettier 配置不同，缩进、属性顺序、引号风格全乱套。
- 把所有公共模板（
header.html、card-template.html）放进pnpm workspace的packages/shared-templates目录 - 业务项目通过
"shared-templates": "file:../shared-templates"引用，禁止本地覆盖同名templates/目录 - 根目录
.htmlvalidate.json统一配置规则（强制img[alt]、禁止内联style、校验lang值格式） - CI 中只跑
pnpm -r --parallel lint:html，失败即阻断合并——别信“我本地过了”
三方协作时怎么让设计、开发、测试看到同一份 HTML 结构契约
设计说“主内容区”，开发写了 <section class="main-content"></section>，测试用 document.querySelector('.main-content') 断言，上线后发现屏幕阅读器根本读不到——因为没语义，也没 role。这不是沟通问题，是缺乏可验证的结构契约。
- 关键区域必须用标准语义标签：
<main></main>、<nav></nav>、<time datetime="2026-07-01"></time>，禁用纯 class 模拟 - 所有交互节点带
data-testid，命名与设计文档一致（如data-testid="search-submit-button"），禁止用button-123这类无意义 ID - 测试脚本必须基于
data-testid定位，禁用依赖 class 名或文本内容的 selector - VS Code 必须统一启用
esbenp.prettier-vscode，且.prettierrc明确写死"tabWidth": 2、"useTabs": false、"htmlWhitespaceSensitivity": "strict"
lang 属性动态切换时最容易漏掉的三个地方
document.documentElement.lang = 'en' 执行完，页面语言就切好了？错。很多团队只改了根节点，却忘了子节点、第三方组件、SSR hydration 后的状态校验，结果富文本里中文被读成英文，Disqus 评论框还是初始语种，字体加载逻辑直接失效。
- Vue/React 中用
v-html或dangerouslySetInnerHTML渲染的内容，需手动设置子节点lang，或加data-lang-sync属性由 JS 统一补全 - 第三方 iframe 组件（如 Disqus、LiveChat）加载后，其内部 DOM 仍继承初始
lang，需监听load事件后主动重设 - SSR 页面中，服务端输出的
lang来自请求头，客户端 hydration 后必须校验是否一致，不一致则触发languagechange事件
