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.