re:re:actable
Урок 053 минуты чтения

Несовпадение 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, или форматирование на клиенте после монтирования
Браузерные APIwindow.innerWidth, localStorage в рендереCSS для адаптивности; useSyncExternalStore с серверным значением; use(browser()) (19.3)
Ветка typeof windowtypeof window !== "undefined" ? <A/> : <B/>Одинаковый первый рендер; различие — после монтирования
Невалидная вложенность<div> внутри <p>, <a> внутри <a>Исправить HTML: браузер «чинит» разметку до гидрации
Данные изменилисьСервер и клиент загрузили разные версииПередавать на клиент тот же снимок (фреймворк делает это сам)
Расширения браузераПереводчики, менеджеры паролей меняют DOMReact 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. Клиентские изменения → после гидрации.

Документация

hydrateRoot.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам