0Pricing
React Academy · 课时

水合错误：原因与修复

识别服务器端与客户端 HTML 之间的不匹配，并使用 suppressHydrationWarning 修复。

水合错误：原因与修复 是 CoddyKit 上的免费 React Academy 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 React Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Academy 课程共包含 4 节课。

什么是水合错误？

当 React 在服务器上渲染的 HTML 与 React 预期在客户端生成的虚拟 DOM 不匹配时，就会发生水合错误。React 会记录警告并从头重新渲染组件，从而造成画面闪烁。

常见原因 1：随机值

在渲染期间使用 Math.random()、Date.now() 或 crypto.randomUUID()，会导致服务器和客户端生成不同的值。

// Bad — different on server vs client:
<div id={Math.random().toString()}>...</div>

// Fix — use useId() (stable across server/client):
import { useId } from 'react';
function Component() {
  const id = useId();
  return <div id={id}>...</div>;
}

常见原因 2：仅限浏览器的 API

在渲染期间读取 localStorage、window.innerWidth 或 navigator，会导致服务器崩溃或生成不同的值。

// Bad — localStorage doesn't exist on server:
<div>{localStorage.getItem('theme')}</div>

// Fix — read in useEffect (client-only):
const [theme, setTheme] = useState('light');
useEffect(() => {
  setTheme(localStorage.getItem('theme') ?? 'light');
}, []);

常见原因 3：日期/时间格式化

本地化日期格式化会在服务器（UTC/Node 区域设置）和客户端（浏览器区域设置）上返回不同的字符串。

// Risky — locale may differ:
<time>{new Date().toLocaleDateString()}</time>

// Fix — use a consistent locale:
<time>{new Date().toLocaleDateString('en-US', { timeZone: 'UTC' })}</time>

常见原因 4：无效的 HTML 嵌套

React 会根据虚拟 DOM 生成客户端 HTML，但无效的 HTML 嵌套（例如在 <p> 内嵌套 <p>）会导致浏览器以不同方式重构 DOM，从而造成不匹配。

// Bad — browser auto-closes the nested <p>:
<p>Outer <p>Inner</p> text</p>

// Fix — use <div> or correct semantic elements:
<div>Outer <p>Inner</p> text</div>

常见原因 5：根据状态进行条件渲染

根据仅存在于客户端的状态（例如用户身份验证、屏幕宽度）进行不同渲染的组件会产生不匹配，因为服务器渲染时没有这些状态。

// Bad — server renders 'Guest', client re-renders 'Alice' immediately:
<h1>{user?.name ?? 'Guest'}</h1>

// Fix — use a mounted guard to defer client-only rendering:
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <h1>Guest</h1>; // match server output

suppressHydrationWarning

对于有意产生不匹配的元素（例如在客户端格式化的时间戳），请使用 suppressHydrationWarning。它只会抑制该元素的警告。

<time suppressHydrationWarning dateTime={isoDate}>
  {new Date(isoDate).toLocaleString()}
</time>

使用 ssr: false 的动态导入

在 Next.js 中，使用 dynamic(fn, { ssr: false }) 可以完全阻止组件在服务器上渲染，从而消除仅限客户端组件的水合不匹配。

import dynamic from 'next/dynamic';

const ClientOnlyChart = dynamic(() => import('./Chart'), { ssr: false });

export default function Dashboard() {
  return <ClientOnlyChart />; // only renders in the browser
}

调试水合错误

React 18 会在开发环境中记录详细的水合错误消息，显示确切的 DOM 节点不匹配位置。使用浏览器 DevTools 检查服务器 HTML 与 React 树的差异。

使用 useId 生成稳定 ID

useId() 会生成在服务器和客户端渲染之间保持一致的稳定唯一 ID，可用于 id/htmlFor 对以及 ARIA 属性。

function FormInput({ label }: { label: string }) {
  const id = useId();
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </div>
  );
}

测试水合错误

在开发模式下运行 Next.js 应用（npm run dev），并查看浏览器控制台。水合不匹配会显示为红色警告，并附带组件堆栈跟踪。

快速检查

如果组件因为读取 localStorage 而在服务器和客户端上的渲染结果不同，最佳修复方法是什么？

回顾

水合不匹配的原因包括：随机值、仅限浏览器的 API、依赖区域设置的格式化、无效的 HTML 嵌套，以及仅限客户端的条件渲染。可使用 useId()、使用 useEffect 处理仅限客户端的状态、使用 suppressHydrationWarning 处理有意差异，以及使用 dynamic({ ssr: false }) 处理仅限客户端的组件。

常见问题解答

「水合错误：原因与修复」课时是免费的吗？

是的 — 「水合错误：原因与修复」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Academy 课程共包含 4 节课。

「水合错误：原因与修复」这节课中我会学到什么？

识别服务器端与客户端 HTML 之间的不匹配，并使用 suppressHydrationWarning 修复。 你通过在浏览器中直接运行的动手代码来练习 React Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。

「水合错误：原因与修复」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Academy 课中编写并运行代码吗？

能。每节 React Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. React SSR 的底层工作原理
  2. 水合错误：原因与修复
  3. 选择性水合与 HTML 流式传输
  4. 岛屿架构模式
← 返回 React Academy