Как исправить ошибку “Hydration failed because the initial UI does not match” в Next.js [Актуальное руководство 2026]

Если вы разрабатываете на Next.js и внезапно столкнулись с ошибкой “Hydration failed because the initial UI does not match what was rendered on the server”, вы не одиноки. Эта ошибка особенно часто встречается в среде React 19 и Next.js 15 с App Router, с тысячами комментариев на GitHub Discussions и постоянно в тренде на Stack Overflow. Данная статья предоставляет полное актуальное руководство на 2026 год по выявлению причин и применению конкретных решений с реальными примерами кода.

Что это за ошибка? Симптомы
Причины возникновения этой ошибки
Решение 1: Изоляция клиентской логики с помощью хука useEffect (Рекомендуется)
Решение 2: Отключение SSR с помощью next/dynamic
Решение 3: Исправление вложенности HTML и правильное использование suppressHydrationWarning
Как предотвратить эту ошибку
Итог
Ссылки

Что это за ошибка? Симптомы

Ошибка гидратации (Hydration Error) в Next.js возникает, когда HTML, отрендеренный на сервере, не совпадает с HTML, который React пытается отрендерить на клиенте при первоначальном рендеринге.

Конкретно, в консоли разработчика браузера появляются следующие сообщения об ошибке:

Unhandled Runtime Error
Error: Hydration failed because the initial UI does not match what was rendered on the server.

Также можно увидеть следующие варианты:

Error: Text content does not match server-rendered HTML.

Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

Когда возникает эта ошибка, Next.js отбрасывает результат серверного рендеринга (SSR) и полностью перерендеривает страницу на клиенте. Это приводит к нескольким серьёзным последствиям:

Значительное снижение производительности: Все преимущества SSR теряются, начальная загрузка страницы становится медленнее
Негативное влияние на SEO: Поисковые роботы могут не получить правильный HTML
Ухудшение пользовательского опыта: Происходит мерцание экрана (вспышка контента)
Ухудшение опыта разработчика: Консоль заполняется ошибками, из-за чего легко пропустить другие проблемы

В Next.js 15 в сочетании с React 19 проверки согласованности гидратации стали строже, и случаи, которые ранее были лишь предупреждениями, теперь рассматриваются как ошибки.

Причины возникновения этой ошибки

Причина 1: Использование API, доступных только в браузере (window / localStorage / document)

Самая частая причина — прямое обращение к API, доступным только в браузере, таким как window, localStorage и document, во время рендеринга. Эти объекты не существуют на стороне сервера.

На сервере эти объекты равны undefined. Поэтому использование условных ветвлений вроде typeof window !== 'undefined' в логике рендеринга вызывает различный вывод на сервере и клиенте, что провоцирует ошибку гидратации.

// ПЛОХО: Это вызывает ошибку гидратации
function MyComponent() {
  const isClient = typeof window !== 'undefined';
  return <div>{isClient ? 'Клиент' : 'Сервер'}</div>;
}

Причина 2: Недетерминированные значения — временные метки и случайные числа

Использование функций, возвращающих разные значения при каждом вызове, таких как new Date() или Math.random(), во время рендеринга вызывает несоответствие между выводом сервера и клиента.

// ПЛОХО: Временная метка различается на сервере и клиенте
function Clock() {
  return <p>Текущее время: {new Date().toLocaleTimeString()}</p>;
}

Между моментом рендеринга на сервере и моментом гидратации на клиенте всегда есть временной сдвиг, поэтому отображаемое время будет различаться, что приводит к ошибке несоответствия текстового содержимого.

Причина 3: Недопустимая вложенность HTML

Недопустимые структуры вложенности, нарушающие спецификацию HTML (например, размещение <div> внутри тега <p>), заставляют HTML-парсер браузера автоматически исправлять DOM, создавая структуру DOM, отличную от HTML, отрендеренного на сервере.

// ПЛОХО: <div> нельзя размещать внутри <p>
function BadNesting() {
  return (
    <p>
      Текст
      <div>Это недопустимая вложенность</div>
    </p>
  );
}

Браузер автоматически исправляет этот невалидный HTML, что вызывает несоответствие между HTML, отправленным сервером, и DOM браузера.

Причина 4: Расширения браузера, изменяющие DOM

Расширения браузера, такие как Colorzilla и Grammarly, могут внедрять атрибуты или HTML-элементы в DOM страницы. Например, Colorzilla добавляет атрибут cz-shortcut-listen="true" к тегу <body>. Это особенно проблематично в средах Next.js 15 + React 19.

Причина 5: Сторонние скрипты и несоответствия контента CMS

Внешние скрипты (рекламные теги, аналитика и т.д.), модифицирующие DOM, или HTML-контент из CMS, содержащий недопустимые структуры вложенности, могут вызывать ошибки гидратации.

Решение 1: Изоляция клиентской логики с помощью хука useEffect (Рекомендуется)

Наиболее эффективное и рекомендуемое решение — переместить логику, зависящую от браузера, в хук useEffect и выводить только детерминированные значения при первоначальном рендеринге.

Шаг 1: Реализация паттерна управления клиентским состоянием

Сначала определите State с одинаковым начальным значением для сервера и клиента, затем обновите его до клиентского значения с помощью useEffect.

'use client';

import { useState, useEffect } from 'react';

function ThemeProvider({ children }) {
  // Используем безопасное для сервера значение в качестве начального состояния
  const [theme, setTheme] = useState('light');
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    // Обращаемся к localStorage только на клиенте
    const savedTheme = localStorage.getItem('theme') || 'light';
    setTheme(savedTheme);
    setMounted(true);
  }, []);

  // До монтирования возвращаем тот же вывод, что и на сервере
  if (!mounted) {
    return <div data-theme="light">{children}</div>;
  }

  return <div data-theme={theme}>{children}</div>;
}

Шаг 2: Установка временных меток и случайных значений внутри useEffect

'use client';

import { useState, useEffect } from 'react';

function Clock() {
  const [currentTime, setCurrentTime] = useState('');

  useEffect(() => {
    const updateTime = () => {
      setCurrentTime(new Date().toLocaleTimeString());
    };
    updateTime();
    const timer = setInterval(updateTime, 1000);
    return () => clearInterval(timer);
  }, []);

  // Показать пустую строку при первоначальном рендеринге (совпадает с сервером)
  return <p>Текущее время: {currentTime || 'Загрузка...'}</p>;
}

Шаг 3: Сделать переиспользуемым с помощью пользовательского хука

Если вы используете этот паттерн в нескольких компонентах, выделите его в пользовательский хук.

'use client';

import { useState, useEffect } from 'react';

// Пользовательский хук для управления состоянием монтирования
function useHasMounted() {
  const [hasMounted, setHasMounted] = useState(false);
  useEffect(() => {
    setHasMounted(true);
  }, []);
  return hasMounted;
}

// Пример использования
function ClientOnlyComponent() {
  const hasMounted = useHasMounted();

  if (!hasMounted) {
    return <div>Загрузка...</div>;
  }

  return <div>Ширина окна: {window.innerWidth}px</div>;
}

Важные замечания

useEffect не выполняется на стороне сервера, поэтому API браузера можно безопасно использовать внутри него
Отображайте плейсхолдер или запасной UI при первоначальном рендеринге для поддержания пользовательского опыта
Этот паттерн может кратковременно показывать плейсхолдер, но это гораздо легче, чем полный перерендеринг страницы из-за ошибки гидратации

Решение 2: Отключение SSR с помощью next/dynamic

Для компонентов, которые сложно обрабатывать с паттерном useEffect (например, сторонние библиотеки, сильно зависящие от API браузера), эффективно полностью отключить SSR с помощью next/dynamic.

import dynamic from 'next/dynamic';

// Импорт с отключённым SSR
const MapComponent = dynamic(
  () => import('../components/Map'),
  {
    ssr: false,
    loading: () => <div className="map-placeholder">Загрузка карты...</div>
  }
);

// Пример использования
function LocationPage() {
  return (
    <div>
      <h1>Расположение магазина</h1>
      <MapComponent />
    </div>
  );
}

Этот метод особенно эффективен в следующих случаях:

Библиотеки карт (Leaflet, Google Maps и др.): Так как они зависят от объекта window
Редакторы форматированного текста (Quill, TipTap и др.): Так как они напрямую манипулируют объектом document
Библиотеки графиков (Chart.js, D3.js и др.): Так как они выполняют операции с DOM SVG или Canvas

Однако компоненты с отключённым SSR не включаются в начальный HTML, поэтому избегайте этого для контента, критичного для SEO. Лучшая практика — ограничить использование интерактивными элементами, не являющимися основным контентом (карты, графики, редакторы и т.д.).

Решение 3: Исправление вложенности HTML и правильное использование suppressHydrationWarning

В качестве продвинутого решения вы можете исправить структуры вложенности HTML и использовать suppressHydrationWarning для неизбежных случаев.

Исправление недопустимой вложенности HTML

Сначала проверьте наличие недопустимой вложенности HTML. Вот типичные недопустимые паттерны и их исправления:

// ПЛОХО: <div> внутри <p>
<p>Текст<div>Блочный элемент</div></p>

// ХОРОШО: Заменить на <div>
<div>Текст<div>Блочный элемент</div></div>

// ПЛОХО: <a> внутри <a>
<a href="/родитель">
  Родительская ссылка
  <a href="/потомок">Дочерняя ссылка</a>
</a>

// ХОРОШО: Устранить вложенность
<div>
  <a href="/родитель">Родительская ссылка</a>
  <a href="/потомок">Дочерняя ссылка</a>
</div>

Ограниченное использование suppressHydrationWarning

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

// Использовать только когда различия допустимы, например для временных меток
<time suppressHydrationWarning>
  {new Date().toLocaleDateString()}
</time>

Важное примечание: suppressHydrationWarning только скрывает ошибку; он не решает основную проблему. Он применяется только к одному уровню глубины текстовых узлов, и несоответствия дочерних элементов по-прежнему обнаруживаются. Используйте с осторожностью и только когда это абсолютно необходимо.

Обработка расширений браузера

Если причиной являются расширения браузера, можно добавить suppressHydrationWarning к тегу <body>.

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="ru">
      <body suppressHydrationWarning>{children}</body>
    </html>
  );
}

Это подавляет предупреждения, вызванные атрибутами, которые расширения добавляют к body. Однако несоответствия в прямых дочерних элементах body по-прежнему обнаруживаются.

Как предотвратить эту ошибку

Для проактивного предотвращения ошибок гидратации включите эти превентивные меры в свой ежедневный рабочий процесс разработки.

1. Обеспечить “детерминированность” первоначального рендеринга

Самый важный принцип — гарантировать идентичный вывод для первоначальных рендерингов сервера и клиента. Значения, зависящие от среды (API браузера, временные метки, случайные числа и т.д.), всегда должны размещаться внутри useEffect.

2. Чётко разделять Server Components и Client Components

В App Router Next.js 15 компоненты по умолчанию являются Server Components. При использовании API браузера или хуков React (useState, useEffect и т.д.) всегда добавляйте директиву 'use client' в начало файла.

3. Использовать правила ESLint

eslint-plugin-react включает правила для обнаружения недопустимой вложенности HTML (например, jsx-no-invalid-html-nesting). Интегрируйте их в свой CI-конвейер для автоматических проверок.

4. Регулярное тестирование

Периодически тестируйте в режиме инкогнито (приватном просмотре) или с отключёнными расширениями браузера для изоляции ошибок, связанных с расширениями.

5. Адаптивный дизайн на основе CSS

Вместо ветвления разметки на основе размера viewport используйте CSS media queries или display: none для переключения видимости, сохраняя согласованную структуру HTML между сервером и клиентом.

// ПЛОХО: Ветвление по viewport в JS
{isMobile ? <MobileNav /> : <DesktopNav />}

// ХОРОШО: Переключение на основе CSS
<MobileNav className="block md:hidden" />
<DesktopNav className="hidden md:block" />

Итог

Ошибка гидратации Next.js “Hydration failed because the initial UI does not match what was rendered on the server” возникает из-за несоответствия между SSR/SSG и клиентским рендерингом и является одной из наиболее часто встречающихся ошибок в разработке на Next.js.

Ключевые выводы:

Суть проблемы — “различные результаты первоначального рендеринга между сервером и клиентом”
Самые частые причины: прямое использование API, доступных только в браузере, рендеринг недетерминированных значений, недопустимая вложенность HTML
Рекомендуемые решения: поэтапный рендеринг с useEffect, отключение SSR с next/dynamic при необходимости
suppressHydrationWarning следует использовать как крайнюю меру, с ограниченной областью применения
Профилактика: обеспечить детерминированность первоначального рендеринга, чётко разделять Server/Client Components

Если эти решения не помогают, проверьте следующее:

Обновите Next.js и React до последних версий
Удалите папки node_modules и .next и пересоберите проект
Поищите похожие случаи в GitHub Discussions Next.js (https://github.com/vercel/next.js/discussions)
Создайте минимальное воспроизведение и сообщите об этом как Issue