Hydration mismatch: причины, обнаружение и правило детерминизма

Компонент приветствия отображает “Доброе утро” или “Добрый вечер” в зависимости от часа. В режиме разработки всё работает. В продакшне пользователи видят мигание: текст меняется в момент загрузки страницы, и layout смещается на 0.14. В консоли браузера: “Text content did not match. Server: ‘Добрый вечер’ Client: ‘Доброе утро’.” Причина — нарушенный контракт под названием hydration mismatch.

Механизм, точно. Гидратация — это контракт: DOM, который клиент создаёт при первом рендере, должен быть структурно идентичен DOM, сериализованному сервером в HTML. React обходит серверный DOM и виртуальное дерево клиента синхронно, усваивая каждый узел. Когда узел не совпадает — разный текст, разные атрибуты, другой элемент, лишний или отсутствующий дочерний элемент — контракт нарушен. Восстановление React: логирует ошибку несоответствия и для затронутого поддерева выбрасывает серверный HTML и рендерит его на клиенте с нуля. Этот recovery render — видимый симптом: мигание изменённого контента и layout shift, который спайкует CLS.

Распространённые причины — все виды недетерминизма между двумя средами: Date.now(), Math.random(), чтение window/document/localStorage во время рендера (undefined на сервере), форматирование Intl в зависимости от локали или timezone, ветки typeof window и расширения браузера, мутирующие DOM до гидратации React.

Правило детерминизма. Лекарство — сделать первый клиентский рендер чистой функцией тех же входных данных, что были у сервера. Любое значение, которое может отличаться между сервером и клиентом, не должно присутствовать во время рендера — оно откладывается в useEffect, который запускается после гидратации, или скрывается за флагом useState(false) “mounted”, переключаемым в эффекте, чтобы и серверный рендер, и первый клиентский рендер выдавали placeholder, и только более поздний рендер вводил клиент-специфичное значение.

Ловушка несоответствия данных. То же ограничение применяется к данным. Если сервер рендерит из одного снимка ответа API, а клиент перезапрашивает более новый до гидратации, деревья расходятся — hydration mismatch, вызванный данными, а не временем или локалью. Исправление: данные сервера должны быть встроены в HTML и повторно использованы клиентом для первого рендера. Именно это делают фреймворки с dehydrated query cache (React Query, Apollo, SWR): сериализуют данные сервера в HTML, реgидрируют их на клиенте, рендерят первый проход из этого кэша, и только потом разрешают свежие запросы.

Сериализация данных и dehydrated cache. Размер встроенного dehydrated cache имеет значение. Очень большой ответ API, сериализованный в HTML, раздувает документ и время парсинга. Иногда правильный компромисс — встроить минимум для above-the-fold контента и перезапросить остальное после гидратации, смирившись с одним дополнительным фоновым запросом ради небольшого документа.

Внутренности streaming SSR. renderToPipeableStream рендерит дерево depth-first и сбрасывает оболочку (shell) — всё вне любых ожидающих Suspense-границ — как только она готова. Для каждой Suspense-границы, данные которой ещё не разрешились, сервер эмитирует fallback inline и держит соединение открытым. Когда данные границы разрешаются, сервер рендерит настоящий контент этой границы и записывает его как чанк: скрытый <div> с контентом плюс крошечный inline <script>, перемещающий его в нужный слот и удаляющий fallback. Браузер, парсящий HTML прогрессивно, выполняет этот скрипт в момент прибытия чанка. Границы стримятся в порядке завершения, а не порядке документа — быстрый виджет внизу страницы может прийти до медленного виджета выше.

Streaming и гидратация переплетаются. По мере того как HTML каждой Suspense-границы поступает потоком, React на клиенте может гидрировать эту границу независимо — не ожидая всего документа. Если пользователь взаимодействует с уже поступившей, но ещё не гидрированной границей, React записывает событие, приоритизирует гидрирование этой границы первой, затем воспроизводит событие. Импликация для senior-разработчика: расположение Suspense-границ — это решение о производительности, а не только о состояниях ошибки/загрузки. Граница вокруг медленного виджета ниже fold позволяет остальной части страницы стримиться и гидрироваться без ожидания; без границы этот виджет блокирует весь документ.

Warning: Text content did not match.
Server: "Добрый вечер" Client: "Доброе утро"
  at Greeting (greeting.tsx:6)
  at Header
  at App

Warning: An error occurred during hydration. The server HTML
was replaced with client content in <div id="greeting">.

[CLS] layout shift: 0.14  (source: #greeting subtree)