Если ошибка возникает у 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/edge | HTML переписан или смешаны варианты | Body hash у origin и edge |
| Build id | HTML и JS от разных выпусков | Версии document и chunks |
Собирайте агрегированные технические признаки, не содержимое страницы и не персональные данные. В отчёте достаточно маршрута, build id, имени компонента, класса различия и хеша нормализованного фрагмента. Текст профиля или заказа в telemetry не нужен.
Три снимка показывают момент расхождения
- Сохранить исходный response body с теми же headers и cookies в разрешённом тестовом сценарии.
- Поставить ранний диагностический код перед запуском приложения и получить хеш корневой разметки.
- Записать сериализованные initial props или их безопасный schema/hash.
- Подключить onRecoverableError и сохранить componentStack, build id и route.
- Сравнить первый клиентский render в том же locale/timezone.
- Повторить в чистом профиле и через прямой 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/version | Version в HTML и API |
| CDN transform | Не переписывать React root | Origin/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.