React / 系统课时

避免水合问题

避免水合问题

水合问题的核心不是“客户端代码不能动态”,而是服务端预渲染的 HTML 与浏览器第一次 React 渲染结果必须一致。本节用一个本地时间组件复现这类风险,并把动态值推迟到水合完成后读取,得到稳定首屏。

学习目标

  • 说明服务端输出与客户端首屏不一致为什么会触发水合错误
  • 识别时间、随机数、浏览器 API 与条件渲染等常见不稳定来源
  • 使用客户端挂载后的状态更新修复问题,并完成可见结果验证

水合失败发生在哪里

Next.js 可以先在服务端生成 HTML,浏览器收到后再由 React 为现有页面绑定交互。水合阶段不是重新随意生成一棵页面树:浏览器第一次渲染应当与服务端已有内容对得上,否则 React 会报告不一致,并可能放弃复用部分内容。

服务端首屏与客户端水合结果对比

最常见的根因都符合“第一次结果不确定”这一特征:渲染阶段直接调用 Date、Math.random(),根据 window 或 localStorage 决定 JSX,服务端与浏览器使用不同环境数据,或者写出浏览器会自动纠正的非法 HTML 嵌套。排查时先寻找首个差异,而不是先隐藏警告。

让首屏保持确定

需要浏览器环境的数据,可以先渲染一个服务端和客户端都相同的占位内容,再在 useEffect 中读取。下面的 app/page.tsx 是可运行示例;页面本身是 Client Component,但它的第一次渲染仍然保持确定。

tsx
'use client'

import { useEffect, useState } from 'react'

export default function Page() {
  const [localTime, setLocalTime] = useState<string | null>(null)

  useEffect(() => {
    // 水合完成后再读取浏览器所在环境的本地时间。
    setLocalTime(new Date().toLocaleTimeString())
  }, [])

  // 服务端输出与浏览器第一次渲染都使用同一占位内容。
  if (localTime === null) {
    return <main>正在读取本地时间…</main>
  }

  return <main>本地时间:{localTime}</main>
}

预期结果

text
首次 HTML / 水合首屏:正在读取本地时间…
水合完成后:本地时间:<TIME>
开发者控制台:没有由该组件产生的 hydration mismatch 警告

<TIME> 会随设备时间和区域设置变化。关键不是最终文本固定,而是服务端 HTML 与浏览器第一次渲染都先输出同一个占位内容,动态值只出现在水合完成之后。

不要用警告开关代替修复

suppressHydrationWarning 适合少量、明确知道会不同且无需 React 修补的文本,它是逃生口而不是通用方案。若差异来自错误的数据来源、条件分支或 DOM 结构,应该消除首屏差异;直接压掉警告会让真正的渲染问题继续存在。

同样地,把整个组件都改成仅客户端渲染虽然能绕开部分水合场景,却会失去相应的预渲染收益。优先让首屏可确定,只把确实依赖浏览器环境的读取延后。

按首个差异定位

开发环境出现水合错误时,先查看错误覆盖层给出的服务端与客户端差异,再回到对应组件检查渲染阶段是否读取了时间、随机值、浏览器 API 或外部可变数据。修复后同时刷新页面并观察控制台,确认差异消失且交互仍正常。

判断是否修好只看一个原则:服务端输出和浏览器第一次渲染必须可重复地得到同一结构与内容。之后发生的状态更新属于正常客户端渲染,不再是水合不一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

避免水合问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通