Vue 3.x水合兼容HTML规范是否明确？非Vue生成内容适配问询

一、Vue 3 水合的核心要求与规范 #

Vue完成客户端水合的核心前提是：服务端输出的HTML，必须和客户端Vue渲染出的DOM结构、内容、属性完全一致，所有细节规则都是围绕这个核心展开的：

• DOM结构严格匹配：节点层级、类型不能有差异，比如服务端输出<div><p>文本</p></div>，客户端渲染结果不能是<div><span>文本</span></div>，否则水合直接失败。
• 文本与实体完全一致：包括空格、换行、HTML实体，比如Vue渲染时会把<转成<，服务端就不能直接写<；换行和空格也要和客户端渲染结果对齐，因为Vue会逐节点对比文本内容。
• 特殊标识不能缺失/修改：
  • 自定义组件的data-v-xxx作用域属性：如果组件用了scoped样式，服务端HTML必须带上对应属性，否则样式失效且水合可能不匹配。
  • 特殊组件的注释标记：比如<Suspense>会生成<!--[-->、<!--]-->这类注释来标记边界，必须严格保留，不然Suspense水合时会出问题。
• 布尔属性格式统一：Vue遵循HTML规范渲染布尔属性，比如disabled只会渲染成<button disabled>，不会写成<button disabled="disabled">，服务端输出必须和这个格式一致。
• 大小写规则：
  • HTML标签、属性名必须是小写，因为Vue模板编译会统一转成小写，不能用<DIV>或者DATA-V-XXX这种格式。
  • Vue的驼峰Props在HTML里要转成短横线格式，比如userName对应user-name，服务端属性必须用短横线写法。
• 类名顺序一致：Vue会按模板里的顺序输出类名，服务端输出的类名顺序必须和客户端完全相同，否则Vue会认为DOM不匹配（因为它会直接对比class属性的字符串内容）。

官方并没有单独针对“第三方生成水合HTML”的详细规范，但在SSR文档里明确了服务端渲染HTML必须和客户端DOM完全一致，这是水合成功的核心准则。

二、复杂场景：非Vue生成HTML的水合注意事项 #

如果要让第三方生成的HTML能被Vue水合，必须严格对齐Vue客户端渲染的结果：

• 先手动用Vue渲染出目标组件的HTML，逐节点对比第三方生成的内容，确保每一个细节（节点、属性、文本、注释）都完全匹配。
• 不要随意修改Vue SSR生成的注释、data属性等内容，这些都是Vue水合时的标识，缺失或改动会导致水合失败，要么触发DOM重新渲染（浪费SSR的性能优势），要么直接报错。
• 处理好DOM规范化：浏览器会自动补全闭合标签、修正格式，服务端输出的HTML必须是浏览器规范化后的结构，和Vue渲染结果一致，比如Vue渲染<img src="xxx">，服务端不能输出<img src="xxx"></img>。

三、关于社区支持的问题 #

Vue社区并没有官方声明禁止第三方生成可水合的HTML，但这种做法确实不在官方推荐的SSR流程里：

• 官方提供的Nuxt、Vue SSR插件已经封装了从服务端渲染到客户端水合的完整流程，能自动保证DOM一致性，官方更推荐用这些工具。
• 第三方自行生成HTML很容易出现DOM不匹配的问题，排查起来非常麻烦，所以社区相关的讨论和文档比较少。
• React社区情况类似，官方同样更推荐用官方SSR方案，自行维护DOM一致性的成本太高，很少有人这么做。

内容的提问来源于stack exchange，提问作者jonas