Если ошибка возникает у 2% пользователей, ищите признак, который отличает эти 2%. React прикрепляет обработчики к уже выданному HTML и ожидает, что первый клиентский render даст ту же структуру. Значит, полезный вопрос звучит не «почему React капризничает», а «какое входное значение изменило дерево между сервером и браузером».

Не включайте suppressHydrationWarning на контейнере приложения. React называет его escape hatch: он работает только на один уровень и не исправляет различие. Сначала локализуйте первый несовпавший узел и источник его данных.

Cohort ошибки строится до изменения кода

ПризнакПочему он может менять HTMLКак сравнить
Locale/timezoneДата и число форматируются иначеResolved options и server locale
Cookie/экспериментВыбрана другая ветка компонентаVariant id и response cache key
User-Agent/deviceУсловный mobile renderОдин URL с теми же headers
РасширениеDOM изменён до загрузки ReactЧистый профиль и DOM before hydrate
CDN/edgeHTML переписан или смешаны вариантыBody hash у origin и edge
Build idHTML и JS от разных выпусковВерсии document и chunks

Собирайте агрегированные технические признаки, не содержимое страницы и не персональные данные. В отчёте достаточно маршрута, build id, имени компонента, класса различия и хеша нормализованного фрагмента. Текст профиля или заказа в telemetry не нужен.

Три снимка показывают момент расхождения

  1. Сохранить исходный response body с теми же headers и cookies в разрешённом тестовом сценарии.
  2. Поставить ранний диагностический код перед запуском приложения и получить хеш корневой разметки.
  3. Записать сериализованные initial props или их безопасный schema/hash.
  4. Подключить onRecoverableError и сохранить componentStack, build id и route.
  5. Сравнить первый клиентский render в том же locale/timezone.
  6. Повторить в чистом профиле и через прямой origin без HTML-модификации.

Если response уже отличается между origin и edge, компонент пока ни при чём. Если response одинаков, но DOM before hydrate изменён, смотрите расширения, browser features и скрипты, выполняющиеся раньше React. Если DOM совпадает, а первый render другой, сравнивайте данные и ветвления JSX.

Recoverable error получает технический контекст

hydrateRoot(container, <App initialData={initialData} />, {
  onRecoverableError(error, errorInfo) {
    reportHydrationIssue({
      name: error.name,
      message: sanitize(error.message),
      componentStack: errorInfo.componentStack,
      route: location.pathname,
      buildId: window.__BUILD_ID__,
      locale: navigator.language,
      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
      initialDataHash: hashShape(initialData)
    });
  }
});

React предоставляет onRecoverableError как часть hydrateRoot. Не отправляйте туда outerHTML всей страницы: он может содержать пользовательский текст. Санитизируйте сообщение, ограничьте component stack, хешируйте только стабильную форму данных и задайте sampling, чтобы повторяющаяся ошибка не заполнила канал наблюдаемости.

Выборочность обычно выдаёт конкретную ветку

  • Date.now(), Math.random() и новый UUID внутри render дают разный результат.
  • Форматирование даты в timezone браузера расходится с серверной зоной.
  • typeof window или matchMedia выбирает другую структуру на первом render.
  • Данные изменились после SSR, но snapshot не передан вместе с HTML.
  • Невалидная вложенность HTML браузер исправил до hydration.
  • Расширение или edge-оптимизатор переписал разметку.

Next.js отдельно перечисляет browser extensions и некорректно настроенный CDN, изменяющий HTML, среди причин. Ошибка «только у пользователей» поэтому не доказывает дефект конкретного браузера: проблема может следовать за регионом CDN, cookie эксперимента или расширением.

Исправление сохраняет одинаковый первый render

Сервер и клиент должны получить один snapshot и одинаковые правила форматирования. Браузерную информацию читайте после hydration через Effect, если она действительно нужна только клиенту; до этого показывайте устойчивую оболочку. Для компонента, который принципиально не имеет серверного представления, можно осознанно отключить SSR средствами фреймворка, понимая цену для загрузки и SEO.

ПричинаИсправлениеКонтроль
Время/случайностьПередать готовое значение в initial dataОдин hash server/client
Locale/timezoneЯвно передать параметры форматаГраница суток и язык
Browser APIЧитать после hydrationПервый render одинаков
Изменяемые данныеПередать snapshot/versionVersion в HTML и API
CDN transformНе переписывать React rootOrigin/edge body hash
РасширениеМинимальный repro и устойчивый markupЧистый/обычный профиль

Регрессия проверяет матрицу, а не один localhost

Добавьте сценарии минимум для двух timezone, двух locale, logged-in/out, варианта эксперимента и двух build id во время rolling deploy. Отдельно запустите browser profile с расширением, которое воспроизводило проблему. Тест должен падать при recoverable hydration error, даже если экран визуально выглядит нормально.

Исправление принято, когда один и тот же snapshot даёт одинаковый server HTML и первый client render, onRecoverableError молчит на целевой матрице, а переходы остаются интерактивными. Для дальнейшего разбора подготовьте минимальный компонент, безопасные initial data, route, build id, component stack и различающий cohort.

Проверенные источники