从一次页面闪烁说起
假设你在维护一个电商商品详情页，服务端用 React 18 的 renderToPipeableStream 输出 HTML，客户端用 hydrateRoot 接管。首屏大部分内容正常，但页面中有一个显示“今日特价倒计时”的组件，它直接渲染了 new Date().toLocaleString()。第一次加载时，页面先显示服务端生成的时间，随后浏览器控制台出现警告：Text content does not match server-rendered HTML，紧接着整个页面被强制重新渲染，闪烁一下后才稳定。
这个现象在传统 SSR 中也可能出现，但换成流式 SSR 后，发生频率和影响范围都变了。原因在于流式传输把 HTML 拆成了多个分块，每个分块到达客户端的时间不同，而 Hydration 要求客户端首次渲染的虚拟 DOM 与服务端生成的 HTML 完全一致。本文以这个倒计时组件为贯穿场景，分析流式渲染为什么更容易触发水合不一致，以及有哪些工程手段可以规避。
传统 SSR 的完整性与流式 SSR 的分块
在 React 18 之前，服务端渲染走的是 renderToString：服务端等待所有组件的数据就绪，一次性渲染出完整的 HTML 字符串，再整体发送给客户端。客户端收到后，执行 JavaScript，调用 ReactDOM.hydrate 把事件绑定到已有的 DOM 上。这个流程的关键约束是：服务端输出的 HTML 必须和客户端首次渲染的虚拟 DOM 结构一致，否则 Hydration 就会失败。
流式 SSR 改变了发送方式。renderToPipeableStream 允许服务端先发送不依赖异步数据的“外壳”HTML，比如页面头部、导航栏、商品标题，然后当某个被 <Suspense> 包裹的组件的数据就绪后，再以独立分块发送该组件的 HTML。浏览器通过 HTTP 的 Transfer-Encoding: chunked 机制接收这些分块，并逐步渲染。这样首字节时间（TTFB）更短，用户能更快看到页面骨架。
但分块传输带来一个副作用：服务端渲染某个组件的时间点与客户端 Hydration 该组件的时间点之间，间隔被拉大了。传统 SSR 中，整个 HTML 一次性到达，客户端开始 Hydration 时，所有服务端渲染已经完成，时间差只有网络传输时间。流式 SSR 中，第一个分块可能已经在用户屏幕上显示了几百毫秒，而最后一个分块（比如倒计时组件）才刚到。如果组件内部使用了当前时间、随机数这类不稳定值，服务端渲染时的值和客户端 Hydration 时的值必然不同，水合不一致就发生了。
Hydration 的匹配机制与失败后果
Hydration 的本质是复用服务端生成的 DOM，而不是重新创建。React 的 hydrateRoot 会遍历已有的 DOM 树，为每个节点生成对应的虚拟 DOM，然后与客户端组件首次渲染的虚拟 DOM 进行比对。比对通过时，直接挂载事件监听器；比对失败时，React 会丢弃该节点及其子树，在客户端重新渲染一遍。
比对的内容包括节点类型、属性、文本内容。文本节点是最容易出问题的：服务端输出 2026年6月8日 14:30:25，客户端渲染时 Date.now() 已经变成了 14:30:26，文本内容不一致，Hydration 失败。属性也一样，比如服务端根据 Math.random() 生成了一个 data-id，客户端重新计算得到另一个值。
失败后 React 的行为分两种情况。开发环境下，控制台会输出 warning，并尝试在客户端重新渲染发生冲突的子树。生产环境下，warning 被抑制，但客户端仍会执行一次完整的客户端渲染来替换服务端生成的 DOM。这带来的后果包括：页面闪烁、首屏性能指标（FCP、LCP）下降、事件绑定延迟，甚至某些节点的状态丢失。
值得注意的是，Hydration 失败并不总是立即导致视觉异常。如果差异只发生在文本内容上，用户可能只看到一次短暂的时间跳动；但如果差异发生在结构层面——比如服务端渲染了一个 <div>，客户端渲染成了 <span>——React 会删除整个子树并重建，这会导致该区域内的所有交互状态（如输入框内容、滚动位置）丢失。
流式渲染如何放大不一致风险
流式 SSR 放大了水合不一致的风险，主要体现在三个方面。
第一，渲染时间窗口被拉长。传统 SSR 中，服务端渲染整个页面只需要几十毫秒，客户端 Hydration 在页面加载后立即开始，两者之间的时间差很小。流式 SSR 中，第一个分块可能在数据请求完成前就发送了，最后一个分块可能延迟数百毫秒甚至更久。如果组件内使用了 Date.now()，服务端渲染时和客户端 Hydration 时的时间差可能从几毫秒扩大到几百毫秒，几乎必然不一致。
第二，<Suspense> 边界内的组件更容易被延迟渲染。流式 SSR 中，被 <Suspense> 包裹的组件如果依赖异步数据，服务端会先发送一个占位符（fallback），等数据就绪后再发送真正的 HTML。这个过程中，占位符和最终内容之间的切换发生在客户端，如果最终内容中包含不稳定值，客户端 Hydration 时拿到的值与服务端渲染时的值不同，就会触发 mismatch。
第三，选择性 Hydration 让不一致的检测时机变得不可预测。React 18 引入了选择性 Hydration：客户端不需要等待所有 JavaScript 加载完成，就可以对已经就绪的 HTML 部分进行 Hydration。这意味着某个组件的 Hydration 可能在另一个组件的 HTML 还在传输时就开始了。如果先 Hydration 的组件依赖了尚未到达的数据，或者使用了不稳定值，错误就会提前暴露，而且可能影响后续组件的 Hydration 顺序。
下面用流程图展示流式 SSR 中一个动态内容组件的完整生命周期，以及不一致发生的节点。
flowchart TD
A[浏览器请求页面] --> B[服务端开始渲染外壳 HTML]
B --> C[发送外壳分块]
C --> D[浏览器渲染外壳并显示骨架]
B --> E[服务端等待倒计时组件数据]
E --> F[数据就绪后渲染倒计时 HTML]
F --> G[发送倒计时分块]
G --> H[浏览器接收分块并追加 DOM]
H --> I[客户端 JS 加载完成，开始 Hydration]
I --> J[React 比对虚拟 DOM 与现有 DOM]
J --> K{文本内容是否一致?}
K -- 否 --> L[丢弃该节点子树，客户端重渲染]
K -- 是 --> M[绑定事件，组件可交互]
L --> N[页面闪烁，性能下降]
流程中的关键转折点在第 7 步到第 9 步之间：服务端渲染倒计时组件的时间点（第 5 步）与客户端 Hydration 的时间点（第 9 步）相隔了网络传输和 JS 执行的时间。如果倒计时组件内部使用了 new Date()，服务端渲染时的值和客户端 Hydration 时的值必然不同，导致第 10 步的判断失败。
不稳定值的来源与典型场景
水合不一致的根源是服务端与客户端执行环境不同，但代码却依赖了运行时环境。最常见的三类不稳定值如下。
时间相关值：Date.now()、new Date().toLocaleString()、performance.now() 等。服务端渲染时的时间与客户端 Hydration 时的时间几乎不可能相同，差异至少是网络传输时间加上 JS 执行时间。在流式 SSR 中，这个差异被进一步放大。
随机数：Math.random() 用于生成唯一 ID、随机排序、A/B 测试分组等。服务端和客户端各自调用一次，结果不同。例如 list.sort(() => Math.random() - 0.5) 在服务端和客户端会产生不同的顺序，导致 DOM 结构不一致。
浏览器专属 API：window.innerWidth、navigator.userAgent、localStorage 等。服务端没有 window 对象，直接引用会报错；即使用 typeof window !== 'undefined' 做保护，服务端渲染出的结果（通常是默认值）与客户端渲染出的结果（真实值）也可能不同。
非确定性数据：服务端请求 API 获取的数据与客户端再次请求时，数据可能已经变化。例如商品库存、用户积分等。传统 SSR 中，如果服务端和客户端各自请求一次数据，也可能不一致；流式 SSR 中，由于分块传输，这种不一致更容易被观察到。
HTML 结构不合法：比如在 <p> 标签内嵌套 <div>，浏览器解析时会自动修正 DOM 结构，导致服务端输出的 HTML 字符串与浏览器实际构建的 DOM 树不一致。这虽然不是流式渲染特有的问题，但在流式场景下，客户端 Hydration 时面对的是经过浏览器修正的 DOM，与服务端生成的虚拟 DOM 差异可能更大。
避免不一致的策略与权衡
针对上述不稳定值，工程上有几种常用策略，各有适用场景和代价。
策略一：延迟到客户端执行
最直接的做法是把依赖运行时环境的值放到 useEffect 或 onMounted 中计算，初始渲染时使用一个稳定的占位值。例如倒计时组件：
function Countdown() {
const [time, setTime] = useState('');
useEffect(() => {
setTime(new Date().toLocaleString());
}, []);
return <div>{time}</div>;
}这样服务端渲染的是空字符串，客户端首次渲染也是空字符串，Hydration 通过。之后 useEffect 触发，更新为真实时间。代价是首屏会短暂显示空白或占位符，且组件在 Hydration 后多一次更新，可能引起轻微闪烁。如果占位符与真实内容尺寸差异大，还可能造成布局偏移。
策略二：使用客户端专用组件
在 Nuxt 中可以用 <ClientOnly> 包裹组件，在 Next.js 中可以用 next/dynamic 配合 ssr: false。这些组件只在客户端渲染，服务端不输出其 HTML，因此不会产生不一致。代价是这些组件的内容无法被搜索引擎爬取，且首屏会延迟到客户端渲染完成才显示，对 SEO 和首屏性能有负面影响。
策略三：抑制 Hydration 警告
React 提供了 suppressHydrationWarning 属性，可以告诉 React 忽略某个节点的文本或属性差异。例如：
<div suppressHydrationWarning>{new Date().toLocaleString()}</div>这个属性只对单个节点生效，且只抑制警告，不会阻止客户端重渲染。如果差异发生在结构层面，suppressHydrationWarning 无效。它的适用场景是：你明确知道该节点的内容在服务端和客户端必然不同，且这种差异不影响功能。代价是掩盖了潜在问题，如果未来该节点的渲染逻辑发生变化，可能隐藏真正的错误。
策略四：保证数据只在一侧生成
对于数据不一致问题，更根本的解法是让服务端和客户端共享同一份数据。在 Next.js 中，可以使用 useAsyncData 或 fetch 配合缓存，确保客户端复用服务端获取的数据，而不是重新请求。例如：
const { data } = useAsyncData('product', fetchProduct);这样服务端渲染时获取的数据会序列化到 HTML 中，客户端 Hydration 时直接使用这份数据，不会再次请求。代价是增加了 HTML 体积（数据被内联），且需要处理数据过期问题。
策略五：条件渲染依赖客户端状态
对于依赖视口宽度、设备类型等客户端状态的条件渲染，可以先用一个默认值渲染，然后在客户端更新。例如：
const [isMobile, setIsMobile] = useState(false);
useEffect(() => {
setIsMobile(window.innerWidth < 768);
}, []);服务端和客户端首次渲染都输出“桌面版”内容，Hydration 通过，之后在客户端切换到移动版。代价是移动端用户首屏会短暂看到桌面版内容，可能影响体验。
策略对比与选型建议
下表对比了上述策略在几个关键维度上的表现。
| 策略 | 首屏一致性 | 首屏性能 | SEO | 实现复杂度 | 适用场景 |
|---|---|---|---|---|---|
| 延迟到客户端执行 | 高 | 中（可能闪烁） | 中（内容为空） | 低 | 时间、随机数等一次性值 |
| 客户端专用组件 | 高 | 低（延迟渲染） | 低（无内容） | 低 | 交互复杂、不依赖 SEO 的组件 |
| suppressHydrationWarning | 中（仅抑制警告） | 中（仍会重渲染） | 高（内容保留） | 低 | 明确知道差异且不影响功能 |
| 数据只在服务端生成 | 高 | 高（无额外请求） | 高 | 中 | 依赖服务端数据的场景 |
| 条件渲染延迟更新 | 高 | 中（可能闪变） | 高 | 中 | 依赖视口、设备类型等 |
从表中可以看出，没有一种策略是万能的。选择时需要权衡首屏体验、SEO 和实现成本。对于倒计时组件这种一次性值，延迟到客户端执行是最简单的方案；对于需要 SEO 的静态内容，应避免使用客户端专用组件；对于数据不一致，优先考虑数据复用。
生产环境中的诊断与降级
在实际项目中，水合不一致往往不是单个组件的问题，而是多个因素叠加的结果。诊断时，应遵循以下步骤。
首先，关注开发环境的第一个 warning。React 会在控制台输出具体的节点信息和差异描述，锁定报错节点。其次，检查该节点是否使用了时间、随机数、浏览器 API 等不稳定值。再次，查看条件渲染是否依赖客户端状态。最后，确认数据是否在服务端和客户端被重复请求。
如果无法立即修复，可以采取降级方案。例如，将整个页面降级为客户端渲染（CSR），即服务端只输出一个空壳，所有内容由客户端渲染。这虽然会牺牲首屏性能，但能彻底避免水合不一致。React 的 renderToPipeableStream 提供了 onShellError 回调，可以在服务端渲染失败时返回 CSR 模板。
另外，suppressHydrationWarning 可以作为临时手段，但不应滥用。它只适合那些你明确知道差异无害的节点，比如用户头像的 src 属性可能因 CDN 路径不同而不同。对于结构差异，它无能为力。
边界条件与框架版本差异
流式 SSR 的行为在不同框架和版本中有所差异。React 18 引入了 renderToPipeableStream，React 19 继续支持并增加了 resume 等 API。Next.js 的 App Router 默认使用流式渲染，并提供了 loading.js 文件来定义 Suspense 的 fallback。Nuxt 3 也支持流式渲染，但 API 不同。
需要明确的是，流式传输本身并不直接导致水合不一致，它只是改变了 HTML 的到达时间和渲染顺序。不一致的根本原因仍然是代码依赖了运行时环境。但流式渲染让这些问题更容易暴露，因为服务端和客户端的渲染时间差被拉大了。
此外，suppressHydrationWarning 在 React 和 Vue 中的行为不同。React 中它只作用于单个节点，Vue 中类似的机制是 v-html 或 v-once，但都不建议用来掩盖问题。
最后，如果页面大部分内容是静态的，可以考虑使用静态生成（SSG）而不是 SSR。SSG 在构建时生成 HTML，不存在服务端与客户端的时间差，水合不一致的风险大幅降低。但 SSG 不适用于内容频繁变化的页面，比如实时库存、用户个性化内容等。
流式 SSR 是一项提升首屏性能的技术，但它对组件渲染的“纯度”提出了更高要求。理解 Hydration 的匹配机制，识别不稳定值的来源，选择合适的规避策略，才能在不牺牲性能的前提下避免水合错误。