Kategoria: Next.js, React i TypeScript

Next.js: Hydration failed — jak znaleźć i naprawić błąd?

Poradnik techniczny · Kacper Bernecki

Komunikat Hydration failed oznacza, że HTML wygenerowany na serwerze różni się od pierwszego renderowania Reacta w przeglądarce. Nie zaczynaj od wyłączania SSR: znajdź element, który ma inną wartość przy pierwszym renderze.

1. Znajdź pierwszy rozjechany element

Otwórz konsolę DevTools i sprawdź fragment drzewa komponentów pokazany przy błędzie. Nie skupiaj się wyłącznie na najwyższym komponencie: istotny jest pierwszy element z rozbieżną zawartością. Jeśli problem jest tylko w jednej przeglądarce, sprawdź rozszerzenia modyfikujące HTML.

Zweryfikuj też zagnieżdżenie HTML. Element p nie może zawierać kolejnego p ani div, a przycisk nie powinien zawierać drugiego przycisku. Przeglądarka może automatycznie poprawić niepoprawny HTML i spowodować rozjazd przy hydratacji.

2. Sprawdź dane zależne od przeglądarki

Najczęstszy błąd: podczas renderowania używasz window, localStorage, losowej liczby albo bieżącego czasu. Serwer i klient mogą wtedy zwrócić różne treści. W React stan początkowy powinien generować identyczny HTML; odczyt lokalnych ustawień wykonaj dopiero w useEffect.

Jeżeli aplikacja renderuje datę, sformatuj ją deterministycznie: jawnie wskaż locale i timeZone albo pokaż wartość po zamontowaniu komponentu. Różne strefy czasowe po stronie serwera i telefonu to częsty powód.

3. Napraw przyczynę, nie ukrywaj ostrzeżenia

Po wprowadzeniu poprawki uruchom kompilację produkcyjną i sprawdź tę samą podstronę bez cache oraz w trybie prywatnym. suppressHydrationWarning stosuj wyłącznie do pojedynczych treści, które muszą się różnić, np. czasu; nie jest uniwersalnym rozwiązaniem. Wyłączanie SSR w całym widoku pogarsza często wydajność i SEO.

Jeśli renderowanie różni się wyłącznie z powodu biblioteki zależnej od DOM, wydziel ją do osobnego klientowego komponentu i dopiero tam rozważ renderowanie bez SSR. Zachowaj po stronie serwera ważny tekst, nagłówki i linki.