Błędy hydratacji: przyczyny i rozwiązania
Rozpoznawanie niezgodności między HTML-em serwera i klienta oraz naprawianie ich za pomocą suppressHydrationWarning.
Błędy hydratacji: przyczyny i rozwiązania to bezpłatna lekcja React Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej React Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs React Academy zawiera 4 lekcji w sumie.
Czym jest błąd hydratacji?
Błąd hydratacji występuje, gdy HTML wygenerowany przez React na serwerze nie pasuje do wirtualnego DOM-u oczekiwanego przez React po stronie klienta. React rejestruje ostrzeżenie i ponownie renderuje komponent od początku, powodując mignięcie interfejsu.
Typowa przyczyna 1: wartości losowe
Użycie Math.random(), Date.now() lub crypto.randomUUID() podczas renderowania powoduje wygenerowanie różnych wartości na serwerze i kliencie.
// Bad — different on server vs client:
<div id={Math.random().toString()}>...</div>
// Fix — use useId() (stable across server/client):
import { useId } from 'react';
function Component() {
const id = useId();
return <div id={id}>...</div>;
}Typowa przyczyna 2: API dostępne tylko w przeglądarce
Odczytywanie localStorage, window.innerWidth lub navigator podczas renderowania powoduje awarię na serwerze albo zwraca różne wartości.
// Bad — localStorage doesn't exist on server:
<div>{localStorage.getItem('theme')}</div>
// Fix — read in useEffect (client-only):
const [theme, setTheme] = useState('light');
useEffect(() => {
setTheme(localStorage.getItem('theme') ?? 'light');
}, []);Typowa przyczyna 3: formatowanie daty i czasu
Formatowanie dat zależne od ustawień regionalnych zwraca różne ciągi na serwerze (ustawienia regionalne UTC/Node) i kliencie (ustawienia regionalne przeglądarki).
// Risky — locale may differ:
<time>{new Date().toLocaleDateString()}</time>
// Fix — use a consistent locale:
<time>{new Date().toLocaleDateString('en-US', { timeZone: 'UTC' })}</time>Typowa przyczyna 4: nieprawidłowe zagnieżdżenie HTML
React generuje HTML klienta na podstawie wirtualnego DOM-u, ale nieprawidłowe zagnieżdżenie HTML (np. <p> wewnątrz <p>) powoduje, że przeglądarki rekonstruują DOM w różny sposób, co prowadzi do niezgodności.
// Bad — browser auto-closes the nested <p>:
<p>Outer <p>Inner</p> text</p>
// Fix — use <div> or correct semantic elements:
<div>Outer <p>Inner</p> text</div>Typowa przyczyna 5: renderowanie warunkowe zależne od stanu
Komponenty renderowane w różny sposób na podstawie stanu dostępnego tylko po stronie klienta (takiego jak uwierzytelnienie użytkownika lub szerokość ekranu) są niezgodne, ponieważ serwer renderuje je bez dostępu do tego stanu.
// Bad — server renders 'Guest', client re-renders 'Alice' immediately:
<h1>{user?.name ?? 'Guest'}</h1>
// Fix — use a mounted guard to defer client-only rendering:
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <h1>Guest</h1>; // match server outputsuppressHydrationWarning
Proszę użyć suppressHydrationWarning na elementach, w przypadku których niezgodności są zamierzone (np. przy znacznikach czasu formatowanych po stronie klienta). Ostrzeżenie zostanie wyciszone tylko dla tego elementu.
<time suppressHydrationWarning dateTime={isoDate}>
{new Date(isoDate).toLocaleString()}
</time>Import dynamiczny z ssr: false
W Next.js proszę użyć dynamic(fn, { ssr: false }), aby całkowicie uniemożliwić renderowanie komponentu na serwerze — eliminuje to niezgodności hydratacji w komponentach dostępnych tylko po stronie klienta.
import dynamic from 'next/dynamic';
const ClientOnlyChart = dynamic(() => import('./Chart'), { ssr: false });
export default function Dashboard() {
return <ClientOnlyChart />; // only renders in the browser
}Debugowanie błędów hydratacji
React 18 rejestruje w trybie deweloperskim szczegółowe komunikaty o błędach hydratacji, wskazujące dokładny węzeł DOM, który jest niezgodny. Do sprawdzenia HTML serwera i drzewa React należy użyć narzędzi deweloperskich przeglądarki.
useId dla stabilnych identyfikatorów
useId() generuje stabilne, unikatowe identyfikatory zgodne podczas renderowania na serwerze i kliencie — należy go używać dla par id/htmlFor oraz atrybutów ARIA.
function FormInput({ label }: { label: string }) {
const id = useId();
return (
<div>
<label htmlFor={id}>{label}</label>
<input id={id} />
</div>
);
}Testowanie błędów hydratacji
Aplikację Next.js należy uruchomić w trybie deweloperskim (npm run dev) i obserwować konsolę przeglądarki. Niezgodności hydratacji pojawiają się jako czerwone ostrzeżenia ze śladami stosu komponentów.
Szybkie sprawdzenie
Jak najlepiej naprawić komponent, który renderuje się inaczej na serwerze i kliencie z powodu odczytu localStorage?
Podsumowanie
Niezgodności hydratacji wynikają z: wartości losowych, API dostępnych tylko w przeglądarce, formatowania zależnego od ustawień regionalnych, nieprawidłowego zagnieżdżenia HTML oraz renderowania warunkowego dostępnego tylko po stronie klienta. Można je naprawić za pomocą useId(), useEffect dla stanu dostępnego tylko po stronie klienta, suppressHydrationWarning dla zamierzonych różnic oraz dynamic({ ssr: false }) dla komponentów dostępnych tylko po stronie klienta.
Często zadawane pytania
Czy lekcja „Błędy hydratacji: przyczyny i rozwiązania” jest bezpłatna?
Tak — pełny tekst „Błędy hydratacji: przyczyny i rozwiązania” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu React Academy, przejdź na CoddyKit PRO. Kurs React Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Błędy hydratacji: przyczyny i rozwiązania”?
Rozpoznawanie niezgodności między HTML-em serwera i klienta oraz naprawianie ich za pomocą suppressHydrationWarning. Ćwiczysz React Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć React Academy?
Nie wymagamy żadnego doświadczenia. React Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.
Ile czasu zajmuje lekcja „Błędy hydratacji: przyczyny i rozwiązania”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji React Academy?
Tak. Każda lekcja React Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Jak działa React SSR od środka
- Błędy hydratacji: przyczyny i rozwiązania
- Selektywna hydratacja i strumieniowanie HTML
- Wzorzec architektury wysp