Как исправить ошибку гидрации "Text content does not match server-rendered HTML"?

Гидрация — это процесс, при котором React на клиенте «оживляет» HTML, уже отрендеренный сервером. Если разметка сервера и клиента отличается хотя бы на один символ, React выбрасывает ошибку Text content does not match server-rendered HTML и перерисовывает поддерево, что бьёт по производительности и SEO.

Основные причины

• Использование Date.now(), Math.random(), new Date() прямо в JSX.
• Обращение к window, localStorage, navigator во время рендера.
• Разные локали или часовые пояса на сервере и клиенте.
• Некорректный HTML внутри тегов (например, <p> внутри <p>), который браузер «чинит» по-своему.
• Условный рендеринг, зависящий от данных, доступных только на клиенте.

Как исправлять

Переносите клиентские вычисления в useEffect, чтобы первый рендер совпадал с серверным, а затем состояние обновлялось.

function Clock() {
  const [now, setNow] = useState(null);
  useEffect(() => {
    setNow(new Date().toLocaleTimeString());
    const id = setInterval(() => setNow(new Date().toLocaleTimeString()), 1000);
    return () => clearInterval(id);
  }, []);
  return <span>{now ?? '--:--:--'}</span>;
}

Если компонент вообще не должен рендериться на сервере, используйте динамический импорт:

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

Для осознанных расхождений (например, тема оформления) применяйте suppressHydrationWarning на конкретном элементе, но не как универсальное решение.

Проверка

1. Откройте DevTools и найдите компонент, где возникает ошибка.
2. Сравните серверный HTML (View Source) и клиентский DOM.
3. Уберите из рендера всё, что зависит от окружения.

Итог: применяйте useEffect и динамический импорт для клиентских данных, а suppressHydrationWarning — только точечно, чтобы сохранить преимущества SSR и избежать лишних перерисовок.