Несовпадение HTML при гидрации
На этой странице
Hydration mismatch возникает, когда первый клиентский рендер отличается от HTML сервера. Причину нужно исправлять, а не считать предупреждение безвредным.
Вопрос
Почему серверная и клиентская разметка расходятся и как это предотвращать?
Основная идея
Если сервер показывает текущее время, а клиент вычисляет new Date() позднее, текст может отличаться. Аналогично работают Math.random(), разные часовые пояса, содержимое localStorage и данные API, изменившиеся между запросами. Даже одинаковый компонент даст разные деревья при разных входных данных.
Есть и структурные причины: неправильная вложенность HTML заставляет браузер перестроить DOM до запуска React. Например, браузер исправляет <div> внутри <p>. Расширения тоже могут изменить документ, но сначала следует исключить собственные ошибки приложения.
React рассматривает совпадение как обязательный контракт. Восстановление может включать клиентский рендер поддерева, а несовпадающие атрибуты не гарантированно исправляются. Безопасный подход — один сериализованный исходный снимок данных и детерминированный первый рендер. Клиентские особенности добавляют эффектом после гидрации.
Пример
Компонент для SSR и последующей гидрации; сервер и клиент передают одинаковый initialTime.
import { useEffect, useState } from 'react';
export default function Clock({ initialTime = '2026-10-15T12:00:00.000Z' }) {
const [time, setTime] = useState(initialTime);
useEffect(() => {
const timer = setInterval(() => setTime(new Date().toISOString()), 1000);
return () => clearInterval(timer);
}, []);
return <time dateTime={time}>{time}</time>;
}Первое значение фиксировано и совпадает на сервере и клиенте. Часы начинают обновляться только после клиентского эффекта. В реальном SSR initialTime формирует сервер и передаёт то же значение браузеру.
Как выглядит ошибка (React 19)
Uncaught Error: Hydration failed because the server rendered text didn't match the client.
<Clock>
<time>
+ 12:00:05 ← клиент
- 12:00:00 ← серверReact 19 показывает один дифф вместо десятков предупреждений, поэтому место расхождения видно сразу.
Частые причины и исправления
| Причина | Пример | Исправление |
|---|---|---|
| Время | new Date().toLocaleTimeString() в рендере | Начальное значение с сервера, обновление в эффекте |
| Случайные значения | Math.random(), crypto.randomUUID() в рендере | useId для id; данные — из одного снимка |
| Локаль и часовой пояс | toLocaleDateString() на сервере (UTC) и в браузере (МСК) | Явная локаль и timeZone, или форматирование на клиенте после монтирования |
| Браузерные API | window.innerWidth, localStorage в рендере | CSS для адаптивности; useSyncExternalStore с серверным значением; use(browser()) (19.3) |
Ветка typeof window | typeof window !== "undefined" ? <A/> : <B/> | Одинаковый первый рендер; различие — после монтирования |
| Невалидная вложенность | <div> внутри <p>, <a> внутри <a> | Исправить HTML: браузер «чинит» разметку до гидрации |
| Данные изменились | Сервер и клиент загрузили разные версии | Передавать на клиент тот же снимок (фреймворк делает это сам) |
| Расширения браузера | Переводчики, менеджеры паролей меняют DOM | React 19 игнорирует большинство вставок в <head>/<body>; остальное — не ваша ошибка |
Правильный паттерн «показать после монтирования»
function LocalTime({ iso }) {
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
return (
<time dateTime={iso}>
{mounted ? new Date(iso).toLocaleString() : new Date(iso).toISOString().slice(0, 16)}
</time>
);
}Первый рендер одинаков на сервере и клиенте, локальное форматирование появляется после гидрации. В React 19.3 то же короче: use(browser()) внутри Suspense.
Что важно помнить
suppressHydrationWarning— узкое исключение для неизбежного локального расхождения, а не ремонт всего дерева.- Проверяйте валидность HTML, локаль и одинаковые начальные props.
typeof window !== "undefined"в render может создать mismatch, даже если предотвращает серверную ошибку.
Мини-шпаргалка
Детерминированный render + общий снимок данных + валидный HTML. Клиентские изменения → после гидрации.