React のハイドレーションエラー(Hydration mismatch)の原因と直し方
React の Hydration mismatch は、SSR の HTML とクライアントの初回描画が食い違うと出る。
初回はサーバーと同じ内容を描画し、時刻・乱数・window 依存の値は useEffect の後で反映すれば直る。
公開: 更新:
node bad_date.js サーバの HTML: <p>2026-10-31T02:13:43.336Z</p> console.error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used: ハイドレーション後: <p>2026-10-31T02:13:43.402Z</p>
2026-10-31 に node:20(React 19.3.1 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細
要約
Hydration mismatch は サーバ側でレンダリングした HTML と、クライアント側の React の初回描画結果が一致しない ときに出る。
主な原因は、new Date() の直書き、window 参照、無効な HTML 入れ子、ブラウザ拡張による DOM 書き換えである。
初回はサーバと同じ内容を描画し、差異は useEffect 後に反映する のが基本戦略である。
実行例
node:20 のコンテナで、renderToString の HTML を jsdom の hydrateRoot に読み込ませた。
時刻の直書き・typeof window の分岐・<p> の中の <div> は Hydration failed のエラーを出し、終了コードは 0 のままだった。
時刻を useEffect で入れた版と suppressHydrationWarning を付けた版では、エラーは出なかった。
$ node bad_date.js
サーバの HTML: <p>2026-10-31T02:13:43.336Z</p>
console.error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:
ハイドレーション後: <p>2026-10-31T02:13:43.402Z</p>
$ echo $?
0$ node bad_window.js
サーバの HTML: <p>server</p>
console.error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:
ハイドレーション後: <p>client</p>
$ echo $?
0$ node bad_nesting.js
サーバの HTML: <p><div>本文</div></p>
console.error: In HTML, <div> cannot be a descendant of <p>.
console.error: Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:
ハイドレーション後: <p><div>本文</div></p>
$ echo $?
0$ node solve_effect.js
サーバの HTML: <p>...</p>
ハイドレーション後: <p>2026-10-31T02:13:44.213Z</p>
$ echo $?
0$ node solve_suppress.js
サーバの HTML: <time>2026-10-31T02:13:44.409Z</time>
ハイドレーション後: <time>2026-10-31T02:13:44.409Z</time>
$ echo $?
0— 2026-10-31 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-31 検証(ほか 2 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
- React 19.3.1
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. ランダム値・時刻は useEffect で
function Clock() {
const [now, setNow] = useState<string | null>(null);
useEffect(() => {
setNow(new Date().toLocaleString());
}, []);
return <p>{now ?? "..."}</p>; // SSR でも "..." を出す
}サーバ HTML とクライアント初回描画を 同じ文字列 にしてから、Effect で書き換える。
2. クライアント専用 UI は isClient で守る
const [isClient, setIsClient] = useState(false);
useEffect(() => setIsClient(true), []);
if (!isClient) return null;
return <OnlyOnClient />;公式の hydrateRoot ドキュメント(新しいタブで開く) のとおり、サーバとクライアントが同一木を作る前提に立ち返り、差異は描画後に反映する。
3. 無効な HTML 入れ子を直す
DevTools のコンソールに In HTML, <div> cannot be a descendant of <p>. のように具体的な要素名と場所が出る。
ブラウザのオートクローズで木構造が変わるため、必ず直す。
4. suppressHydrationWarning(限定的)
時刻表示など、本文と乖離が起こりうると承知の上で抑止する場合にだけ使う。
<time suppressHydrationWarning>{new Date().toISOString()}</time>公式の説明(新しいタブで開く) のとおり、不一致を「無視する」だけで根本解決ではない。
子要素にむやみに広げない。
よくある原因
- 時刻・乱数を JSX に直接書いている。
<p>{new Date().toLocaleString()}</p>は、サーバ実行時刻とクライアント実行時刻がズレて mismatch する。 - window に依存して分岐している。
typeof window !== 'undefined' ? <A /> : <B />のような書き方は、サーバとクライアントで異なる枝を選ぶため必ず食い違う。 - HTML のネストが無効になっている。
<p>内の<div>、<button>内の<button>、<a>の入れ子などは、ブラウザが閉じタグを補ってツリー構造が変わる。 - ブラウザ拡張が DOM を書き換えている。
Grammarly やパスワード拡張が<body>属性を書き換えると、最上位ノードで mismatch が起きる。