React SSR 水合备忘录：原理、常见问题与最佳实践

2026-06-06 约 1900 字预计阅读 4 分钟

在 React 的 SSR（服务端渲染）架构中，水合是指：

这个过程本质上是**“让静态 HTML 变成可交互应用”**的桥梁。

水合能够正常工作的唯一必要条件是：客户端首次渲染生成的虚拟 DOM 树，必须与服务端生成的 HTML 结构完全一致。

如果两者存在任何差异，React 会：

在开发环境下打印警告（Hydration mismatch）。
在生产环境下，从不匹配节点向上找到最近的 <Suspense> 边界，丢弃该边界内的服务端 HTML，并在客户端重新渲染该子树；若上方没有 Suspense 边界，则会从根节点丢弃全部服务端 HTML 并客户端重渲染（损害性能并可能造成视觉闪烁或输入状态丢失）。

原因分类	典型表现	解决方案
浏览器特有 API 使用	使用 `window`、`document`、`localStorage`、`navigator` 等	将相关逻辑移到 `useEffect` 或 `useLayoutEffect` 中，或在 `useState` 初始化时使用 `null` 占位，待客户端再更新
时间/随机数差异	`new Date()`、`Math.random()` 在服务端和客户端计算结果不同	使用 `useEffect` 延迟计算，或由服务端生成后通过 props 传入
数据获取时机不一致	服务端使用某种数据源，客户端使用另一份数据	确保服务端和客户端使用完全相同的数据源（如通过 props 传递服务端获取的数据）
第三方脚本污染 DOM	第三方 JS 在 React 水合前修改了 DOM 树	通过 Next.js `<Script>` 的 `afterInteractive` 或 `lazyOnload` 策略延后加载
组件条件渲染路径不同	服务端和客户端因 `typeof window` 等条件渲染了不同分支	使用 `useEffect` 或 `useState` 控制客户端专属内容的展示，或使用 `next/dynamic` 的 `ssr: false`
样式计算差异	CSS-in-JS 库在服务端和客户端生成的类名或样式不同	使用支持 SSR 的样式方案（如 `styled-components` 的 `ServerStyleSheet` 收集样式，或 CSS Modules / Tailwind）

现象：页面 TTFB 很快，但 TTI（可交互时间）很长，用户点击按钮无响应。

原因：整个页面一次性水合，当 DOM 节点数量庞大（如长列表、复杂表格）时，水合过程占用主线程，阻塞交互。

解决方案：

现象：水合完成后，客户端数据获取呈串行链路，一个请求完成后再发起下一个，总耗时叠加。

原因：父组件通过 useEffect 获取数据，数据返回后再渲染子组件，子组件又发起自己的数据请求。

解决方案：

工具	用途
浏览器控制台 / React DevTools	查看 `Hydration mismatch` 警告及组件栈，定位不匹配节点
Chrome DevTools Performance	录制水合阶段的火焰图，识别长任务和阻塞点
`hydrateRoot` 的 `onRecoverableError`	捕获水合可恢复错误，用于上报监控
Next.js 的 `next/script`	控制第三方脚本加载顺序，避免污染水合
`useEffect` 配合 `console.warn`	在客户端显式检测水合差异（如对比服务端注入的数据）

服务端和客户端环境差异：永远不要在组件顶层直接使用浏览器 API；所有动态数据应通过 useState + useEffect 或 Server Component 的 props 传递。
水合一致性：尽可能确保服务端渲染的 HTML 与客户端首次渲染结果相同；使用 suppressHydrationWarning（仅在万不得已时）。
性能策略：采用“流式 SSR + 选择性水合”模式，首屏只水合核心区域，次要区域使用 Suspense 懒水合。
第三方代码隔离：会修改 DOM 的第三方脚本应延后加载（如 Next.js <Script strategy="afterInteractive" /> 或 lazyOnload），避免在水合完成前污染 DOM。
数据获取：优先在 Server Component 中获取数据，通过 use 或 props 传递，减少客户端数据请求。
监控与测试：建立水合错误的监控告警（如 hydrateRoot 的 onRecoverableError），并在 CI 中用 renderToString + hydrateRoot 或 Playwright 等端到端测试检测 mismatch。

检查项	状态
是否有组件使用了 `window` / `document` / `localStorage`？	☐
是否有组件使用了 `new Date()` / `Math.random()` 直接渲染？	☐
是否有组件在 `useEffect` 中串行拉取本可在服务端预取的数据？	☐
是否有第三方脚本在 `DOMContentLoaded` 前修改了 DOM？	☐
是否使用了大量 DOM 节点（如长列表）且未用 `Suspense` 分包？	☐
是否在 `useState` 初始化函数中调用了浏览器 API？	☐
是否在 Server Component 中正确传递了数据给 Client Component？	☐