`を入れるなどの不正なHTMLネスト、(3) Grammarly や ColorZilla などブラウザ拡張によるDOM改変。 - **最短の直し方**：クライアント固有の値は`useEffect`後にセットする、SSR不要な部品は`next/dynamic`で`ssr: false`にする、不正なタグネストを直す。`suppressHydrationWarning`は根本原因を消さない逃げ道なので乱用しない。 ## ハイドレーションエラーとは（ハイドレーションとSSRの仕組み）ハイドレーション（Hydration）とは、サーバーが事前生成したHTMLに対して、ブラウザ側のReactがイベントハンドラや状態を付け直して「操作できるアプリ」に変える処理を指す。SSRやSSG（静的生成）では、まず素早く表示できるHTMLをサーバーで作り、その上にReactがクライアントで同じツリーを再現して結び付ける。この「サーバーのHTML」と「クライアント初回描画」がずれると、ハイドレーションエラーになる。Next.jsでのSSR/CSR/SSGの違いは[Next.jsにおける主要なレンダリング方法の種類と概要](https://www.issoh.co.jp/tech/details/3791/)で整理している。 ### ハイドレーションが行っていること Reactは`hydrateRoot`でHTMLを再利用しようとする。既存のDOMを作り直さず、そこに仮想DOMを重ねてイベントを結線するのがハイドレーションだ。だからこそ、サーバーが出力したマークアップとクライアントの初回レンダリング結果が同じであることが前提になる。 ### 不一致が起きるとツリーが作り直される理由初回描画の結果がサーバーHTMLと一致しないと、Reactはそのツリーを信用できず、クライアント側で描画し直す。React 18以降は該当ツリーを再生成して回復するが、その分だけ画面のちらつき・入力状態のリセット・初期表示の遅延が起きる。React 19では不一致箇所の差分を分かりやすく表示するようエラーが改善された（[React 19とは？18からの変更点・新機能とReact Compiler・最新バージョンを解説](https://www.issoh.co.jp/tech/details/4509/)）。 ## エラーメッセージ別の意味（React error #418 / #423 / #425）本番ビルドではメッセージが省略され「Minified React error #◯◯」とだけ出る。番号とメッセージの対応を押さえておくと、貼り付けられたエラーから原因を絞り込める。代表的なものを整理する。 | エラーメッセージ / 番号 | 意味 | 主な原因 | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------- | | Text content does not match server-rendered HTML.（#425） | テキスト内容がサーバーとクライアントで違う | 時刻・乱数・ロケール依存の文字列 | | Hydration failed because the server rendered HTML didn’t match the client.（#418） | 描画結果が一致せずツリーを再生成 | 条件分岐・動的値・不正なネスト | | There was an error while hydrating but React was able to recover by instead client rendering the entire root.（#423） | 回復したがroot全体をクライアント描画にフォールバック | ハイドレーション不一致からroot全体の再描画で回復 | | A tree hydrated but some attributes of the server rendered HTML didn’t match the client properties. This won’t be patched up. | 属性（class/style等）の不一致。修復されない | ブラウザ拡張のDOM改変・CSS-in-JS設定 | | In HTML, cannot be a child of . This will cause a hydration error. | HTMLの入れ子が仕様違反 | 不正なタグネスト（後述） | ### 本番の「Minified React error #◯◯」を読む方法番号付きメッセージのURL（例：react.dev/errors/418）を開くか、開発ビルド（`NODE_ENV=development`）で動かすと、省略されていた完全なメッセージと該当コンポーネントが表示される。原因調査は本番のminified表示のまま進めず、まず開発ビルドで再現してメッセージを復元するのが早い。 ## ハイドレーションエラーが起きる主な原因 Next.js公式が挙げる典型的な原因は次の通り。いずれも「サーバーとクライアントで描画結果が変わる」ことが共通点だ。 | 原因 | 具体例 | 対処の方向 | | ------------------ | ------------------------------------------ | ------------------ | | 時刻・タイムゾーン・ロケール | `new Date()`、`toLocaleString()` | useEffectでクライアント描画 | | 毎回変わる値 | `Math.random()`、乱数ID | useEffect / 固定シード | | ブラウザ専用API | `window`、`localStorage`、`typeof window`分岐 | useEffect後に参照 | | 不正なHTMLネスト | `

`内の`

`、``の入れ子 | マークアップを修正 | | ブラウザ拡張 | Grammarly、ColorZilla（`cz-shortcut-listen`） | 拡張の切り分け・body限定の抑制 | | CDN / CSS-in-JS 設定 | CDN/プロキシのHTML自動改変、設定ミスのCSS-in-JS | 自動改変の無効化・公式設定 | 特に多いのが、描画のなかで「サーバーでは決まらない値」を直接使うケースだ。次のコードはサーバーとクライアントで時刻が変わるため、ほぼ確実にエラーになる。 ``` // NG: 描画中に毎回変わる値をそのまま使う function Clock() { // サーバーが返した時刻とクライアント描画時の時刻がずれる return

{new Date().toLocaleTimeString()}

; } ``` ## ハイドレーションエラーの対処法原因は違っても、直し方は「サーバーとクライアントの初回描画を一致させる」か「一致しない部分をハイドレーションの対象から外す」のどちらかに集約できる。 ### useEffectでのクライアント限定描画クライアントでしか決まらない値は、初回描画では出さず`useEffect`実行後にセットする。`useEffect`はハイドレーション後に呼ばれるため、`window`などのブラウザAPIをずれなく使える。React公式・Next.js公式ともに推奨する基本パターンだ。 ``` import { useState, useEffect } from 'react'; export default function Clock() { const [time, setTime] = useState(null); useEffect(() => { // クライアントでのみ実行されるので不一致にならない setTime(new Date().toLocaleTimeString()); }, []); return

{time ?? '読み込み中'}

; } ``` `useState`や`useEffect`の基本は[Reactフックの基本と導入：React 16.8で追加された新機能の概要](https://www.issoh.co.jp/tech/details/3671/)を参照。 ### next/dynamicによるSSR無効化グラフ描画やブラウザAPI前提の部品など、そもそもサーバーで描く必要がないコンポーネントは、Next.jsの`dynamic`で`ssr: false`にしてハイドレーション対象から外す。 ``` import dynamic from 'next/dynamic'; // この部品はクライアントでのみ描画される const NoSSR = dynamic(() => import('./Chart'), { ssr: false }); export default function Page() { return ; } ``` ### 不正なHTMLネストの修正「` cannot be a child of `」「`

cannot be a child of

`」のように出る場合は、HTMLの入れ子がブラウザの正規化で書き換えられ、サーバー出力とずれている。`

`の中にブロック要素を置かない、``や`