服务端生成的HTML结构必须与客户端首次渲染的DOM树完全一致，否则触发hydration mismatch错误导致白屏、静默覆盖或交互失效；React/Vue在hydrate阶段复用服务端DOM并逐层比对，差异将破坏SSR性能收益；需统一组件逻辑、初始数据、条件渲染及客户端专属逻辑隔离。
服务端生成的HTML结构必须与客户端首次渲染的DOM树完全一致，否则会触发 hydration mismatch 错误，导致页面白屏或静默覆盖。
hydration mismatch 错误的典型表现
浏览器控制台抛出类似 Warning: Prop `data-reactroot` did not match 或 Hydration failed because the server rendered HTML didn't match the client 的警告；更严重时直接报错中断 hydrate 流程，hydrateRoot 返回 null 或抛出异常；部分组件不响应点击、状态不更新，但无明显报错（静默失败）。
为什么 HTML 结构一致性如此关键
React/Vue 等框架在 hydrate 阶段不会重建 DOM，而是复用服务端已输出的节点，并逐层比对虚拟 DOM 与真实 DOM 的属性、子节点顺序、文本内容。一旦发现差异（如服务端渲染了 <div>Loading...</div>，客户端初始 state 却是空数组并渲染了 <ul></ul>），框架无法安全“打补丁”，只能放弃 hydrate 或强制替换——前者导致交互失效，后者破坏 SSR 的性能收益。
确保结构一致的实操要点
服务端和客户端使用同一套组件逻辑，禁止在 useEffect、mounted 等生命周期中动态插入/删除顶层容器节点；getServerSideProps（Next.js）或 asyncData（Nuxt）返回的数据必须与客户端初始 state 完全相同，包括空数组 [] 和 null 的语义；避免在服务端条件渲染某区块、客户端却无条件渲染（例如：服务端因未登录不渲染购物车徽标，客户端登录态未同步就立即显示徽标）；所有依赖时间、随机数、window 或 navigator 的逻辑必须包裹在 if (typeof window !== 'undefined') 中，且不能影响首屏结构输出。
立即学习“前端免费学习笔记（深入）”；
调试 hydration 不一致的最快路径
打开浏览器开发者工具，对比 Network → HTML 响应体中的原始 HTML 与 Elements 面板中最终渲染的 DOM 树；重点关注根容器内第一层子节点的数量、标签名、data-* 属性值；在客户端入口文件中临时添加 console.log(document.getElementById('root').innerHTML)，与服务端 renderToString 输出字符串做 diff；使用 React DevTools 的 “Highlight updates” 功能观察哪些节点被替换而非复用。
真正难处理的不是“有没有 hydrate”，而是“hydrate 到哪一层为止”——比如广告位、评论区这类强动态区域，与其硬塞进 SSR 再频繁 mismatch，不如从服务端就留空占位符，由客户端接管整个区块的首次渲染。结构一致性不是教条，而是水合生效的底线。
