Hjem
» Grunnleggende kunnskap
»
Slik fikser du feilen «Hydration failed because the initial UI does not match»
Slik fikser du feilen «Hydration failed because the initial UI does not match»
Resultatet du ønsker, er enkelt å beskrive: HTML-en som produseres på serveren, må samsvare med det React produserer ved den første visningen i nettleseren. Når dette er tilfelle, kan React feste hendelsesbehandlere og gjøre siden interaktiv uten å kaste en hydreringsfeil, erstatte en undertre eller vise et uventet visuelt hopp.
Hydrering er prosessen der React tar HTML som allerede er gjengitt på serveren, og fester React-atferd til den i nettleseren. Reacts gjeldende dokumentasjon for hydrateRoot sier at klientgjengitt innhold forventes å være identisk med servergjengitt innhold, og at avvik bør behandles som feil.
Den nøyaktige ordlyden i feilmeldingen har endret seg over ulike versjoner av React og rammeverk. Du kan se en eldre melding som "Hydration failed because the initial UI does not match what was rendered on the server", eller en nyere melding som forklarer at treet gjengitt på serveren ikke samsvarte med klienten. Feilsøkingsprinsippet er det samme.
Versjonskontekst er viktig. Per 11. september 2026 lister den offisielle React-siden React 19.3 som den nyeste React-versjonen, mens den gjeldende Next.js-dokumentasjonen identifiserer Next.js 16.3.4 som den nyeste Next.js-utgivelsen. Sjekk Reacts versjonsside og den gjeldende Next.js-dokumentasjonen hvis du leser dette senere, fordi tilgjengelige API-er og feilmeldinger kan endre seg.
AI-generert illustrasjon: Start med å finne den første komponenten som er nevnt i hydreringsfeilen, og bekreft at problemet oppstår ved en ny sideinnlasting. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
Hva teller som en vellykket fiks?
Døm ikke suksess kun etter om en rød utviklingsoverlay forsvinner. En god fiks bør oppfylle flere sjekkpunkter:
Hydreringsadvarselen eller feilen vises ikke lenger ved en ren omlasting.
Den opprinnelige servergjengitte brukergrensesnittet og nettleserens første React-visning representerer samme innhold og struktur.
Den berørte komponenten forblir interaktiv etter hydrering.
Det er ingen åpenbar blink fra én verdi til en annen, med mindre den endringen er tilsiktet og designet.
Problemet forblir fikset i en produksjonsbygging, ikke bare på utviklingsserveren.
Du har korrigert årsaken i stedet for å skjule et reelt avvik med et alternativ for advarselsundertrykkelse.
Hvis advarselen forsvinner, men siden nå gjengir viktig innhold først etter at JavaScript er lastet, kan feilen være borte mens brukeropplevelsen har blitt verre. Det kan være et rimelig kompromiss for en nettleseravhengig widget, men det er ikke automatisk det beste resultatet for primært sideinnhold.
Steg 1: Reproduser avviket og finn den minste feilende komponenten
Start med en hard omlasting i utviklingsmiljøet og les hele feilmeldingen, inkludert komponentstakken. React 19s dokumenterte hydreringsfeil lister flere vanlige årsaker: server/klient-grener som typeof window !== 'undefined', endrede verdier som Date.now() eller Math.random(), lokalavhengig datoformatering, ekstern data som endret seg uten et øyeblikksbilde, ugyldig HTML-nesting og nettleserutvidelser som endrer DOM-en. Se React-feil 418.
Next.js gir en lignende liste i sin offisielle guide for hydreringsfeil, og legger til nettleseravhengige API-er som window og localStorage, CSS-in-JS-konfigurasjon og HTML endret av et Edge/CDN-lag.
AI-generert illustrasjon: Innskrenk feilen til uttrykket som kan produsere en forskjellig verdi på serveren og i nettleseren, som en dato, tilfeldig tall, lokal eller nettleseravledet verdi. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
En praktisk isolasjonsmetode er å midlertidig erstatte mistenkelige dynamiske seksjoner med deterministisk tekst. Hvis feilen forsvinner, gjenopprett disse seksjonene én om gangen. Dette er vanligvis raskere enn å endre globale gjengivelsesinnstillinger før du vet hvilken komponent som er ansvarlig.
Kvalitetssignal
Du er klar til å gå videre når du kan navngi både den feilende komponenten og verdien eller strukturen som avviker. "Det skjer et sted i dashbordet" er fortsatt for bredt. "Tidsstempelet i StatusCard produseres uavhengig på server og klient" er handlingsbart.
Steg 2: Fjern ikke-deterministiske verdier fra den første gjengivelsen
Deterministisk gjengivelse betyr at de samme inndataene produserer samme første brukergrensesnitt. Verdier som endrer seg uavhengig mellom servergjengivelse og nettlesergjengivelse, er hyppige kilder til avvik.
Vurder dette problematiske mønsteret:
export default function LastUpdated() {
return <time>{new Date().toLocaleString()}</time>;
}
Serveren og nettleseren kan kjøre denne koden på ulike tidspunkter og i ulike lokaliteter eller tidssoner. En bedre løsning avhenger av hva siden skal kommunisere.
Hvis tidsstempelet representerer serverdata, beregn eller hent det én gang på serveren og send den samme serialiserte verdien til klienten:
Hvis verdien genuint avhenger av brukerens nettleser, gjengir du en stabil plassholder først og oppdaterer den etter hydrering.
AI-generert illustrasjon: En stabil startverdi kan hydrere rent, og nettleserspesifikt innhold kan deretter anvendes etter at komponenten er montert. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
Dette fungerer fordi serveren og den første klientgjengivelsen begge produserer den samme plassholderen. Reacts useEffect-dokumentasjon beskriver dette to-trinns mønsteret for de sjeldne tilfellene der klientinnhold må avvike fra serverinnhold.
Når du bør endre tilnærming
Hvis den nettleseravhengige verdien er hele formålet med komponenten – for eksempel en editor gjenopprettet fra localStorage eller en widget som ikke kan gjengis meningsfullt på serveren – kan det å tvinge et plassholder-og-effekt-mønster gjennom hele komponenten legge til unødvendig kompleksitet. I så fall, bruk en bevisst nettleseravhengig grense i stedet for å late som om komponenten er servergjengibar.
Steg 3: Ikke les nettleseravhengige API-er under den første serverkompatible gjengivelsen
En vanlig misforståelse i Next.js er at å legge til 'use client' garanterer at komponenten kun gjengis i nettleseren. Det gjør den ikke. Next.js forklarer at Client Components er grensen for state, effekter, hendelsesbehandlere og nettleser-API-er, men Client Components kan fortsatt delta i forhåndsgjengivelse. Se den gjeldende use client-dokumentasjonen.
På serveren eksisterer ikke localStorage. Selv en gren som typeof window !== 'undefined' kan produsere ulik markup ved den første nettlesergjengivelsen, noe både React og Next.js dokumenterer som en årsak til hydreringsavvik.
For små forskjeller, flytt nettleseravlesningen til en Effect. For en komponent som genuint bør være nettleseravhengig i Next.js, kan du dynamisk laste den inn med SSR deaktivert:
AI-generert illustrasjon: Bruk en klientavhengig grense for komponenter som fundamentalt avhenger av nettleser-API-er, i stedet for å la server og nettleser gjengi ulike trær. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
Next.js dokumenterer ssr: false for Client Components i sin guide for treg lasting. Samme guide sier at ssr: false ikke støttes når du prøver å bruke det alternativet direkte i en Server Component; flytt den dynamiske importen inn i en Client Component.
React 19.3: et førsteklasses nettleseravhengig alternativ
React 19.3 introduserte browser-API-et. En komponent kan kalle use(browser()) inne i en Suspense-grense for å melde den komponenten ut av servergjengivelse. Serveren gjengir Suspense-plassholderen, mens komponenten gjengir normalt i nettleseren. Se Reacts browser API-referanse.
import { Suspense, use } from 'react';
import { browser } from 'react-dom';
function BrowserOnlyContent() {
use(browser('Requires browser APIs'));
return <ActualBrowserContent />;
}
export default function Example() {
return (
<Suspense fallback={<p>Loading...</p>}>
<BrowserOnlyContent />
</Suspense>
);
}
I en React Server Components-applikasjon sier React at use(browser()) må kalles fra en Client Component. Verifiser også at ditt rammeverk og installerte React-versjon eksponerer denne API-en før du tar den i bruk.
Steg 4: Gjør serverdata og den første klientdataen til samme øyeblikksbilde
Et øyeblikksbilde er den nøyaktige datastaten som brukes til å produsere den første HTML-en. Hydrering blir skjør hvis serveren gjengir én dataversjon og klienten umiddelbart leser en nyere eller ulikt sortert versjon før hydreringen er fullført.
AI-generert illustrasjon: Den første klientgjengivelsen bør konsumere det samme innledende dataøyeblikksbildet som produserte server-HTML-en; senere oppdateringer kan skje etter hydrering. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
For eksempel, la oss si at serveren gjengir en pris på $99, men klienten umiddelbart henter det samme produktet og får $109 før sin første gjengivelse. Problemet er ikke at dataene endret seg; endrede data er normalt. Problemet er at de to miljøene brukte forskjellige innledende inndata.
Et sterkt mønster er:
Hent de innledende dataene på serveren.
Gjengir HTML-en fra den dataen.
Send eller serialiser de samme innledende dataene til klientkomponenten.
Tillat klienten å revalidere og oppdatere seg hvis nyere data finnes, etter hydrering.
Den korrekte implementasjonen avhenger av rammeverkets datalastingsmodell, men kvalitetskriteriet forblir det samme: server-HTML-en og det første klienttreet bør basere seg på samme logiske tilstand.
Når du bør endre tilnærming
Hvis innholdet er iboende sanntids og et utdatert serverøyeblikksbilde ville villedet brukere – for eksempel en live-handelswidget eller en raskt endrende operasjonskonsoll – vurder å gjengir et stabilt skallet på serveren og laste den live-seksjonen på klienten. Det gir opp noe servergjengitt innhold for den regionen, men det kan være mer ærlig enn å hydrere mot data som er garantert å endre seg.
Steg 5: Fiks ugyldig HTML før du skylder på React
Nettlesere har lov til å korrigere feilformet eller ugyldig nestet HTML. Den korreksjonen kan produsere en DOM-struktur som avviker fra strukturen React forventer, selv om JSX-en så visuelt plausibel ut.
AI-generert illustrasjon: Sjekk semantisk HTML-nesting når komponenttreet ser deterministisk ut, men nettleseren fortsatt konstruerer en annen DOM. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
Next.js lister uttrykkelig eksempler som en <div> inne i en <p>, en liste inne i et avsnitt, nøstede anker-tagger og nøstede knapper som årsaker til hydreringsproblemer.
For eksempel, unngå:
<p>
Intro text
<div>Details</div>
</p>
<div>
<p>Intro text</p>
<div>Details</div>
</div>
Hvis et komponentbibliotek genererer markupen, inspiser den endelige DOM-en i stedet for å anta at wrapper-elementene er gyldige. En lint-regel eller HTML-validerer kan hjelpe, men nettleserens faktiske DOM er det React hydrerer.
Steg 6: Utelukk kode utenfor komponenten
Hvis gjengivelseslogikken din er deterministisk og HTML-en din er gyldig, sjekk om noe endrer server-HTML-en før React hydrerer den.
Offisiell Next.js-dokumentasjon nevner flere muligheter:
En nettleserutvidelse endrer siden før React lastes.
Et CSS-in-JS-bibliotek er feilkonfigurert for servergjengivelse.
En Edge- eller CDN-funksjon omskriver eller minifiserer HTML-responsen.
På iOS kan automatisk gjenkjenning av telefonnumre, e-postadresser, datoer eller adresser endre tekst til lenker i noen tilfeller.
Bruk kontrollerte sammenligninger. Test i et privat nettleservindu med utvidelser deaktivert. Hvis feilen oppstår kun bak en CDN, sammenlign med opprinnelsesresponsen. Hvis det startet etter at du tok i bruk et stylingbibliotek, følg det bibliotekets offisielle SSR-konfigurasjon i stedet for å anvende en generell hydreringsløsning.
Kvalitetssignal
Du har isolert denne klassen av problemer når samme applikasjonsbygging hydrerer korrekt i ett kontrollert miljø, men feiler etter at en spesifikk nettleserutvidelse, proxy, CDN-transformasjon eller integrasjon endrer HTML-en.
Steg 7: Bruk suppressHydrationWarning kun for en genuint uunngåelig lokal forskjell
React tilbyr suppressHydrationWarning={true} for sjeldne tilfeller der teksten eller attributtene til et enkelt element ikke rimelig kan samsvare, som visse tidsstempler.
Dette er ikke en generell reparasjonsmekanisme. Reacts dokumentasjon for vanlige DOM-props sier at alternativet kun fungerer ett nivå dypt og er ment som en nødutgang. Next.js-hydreringsguiden advarer også om at React ikke vil prøve å lappe sammen mismatchet tekstinnhold når dette alternativet brukes.
Forskjellen er forventet og lokalisert.
Avviket representerer ikke feil applikasjonstilstand.
Den omgivende strukturen er stabil.
Du har bevisst akseptert at den innledende serververdien og nettleserverdien avviker.
Hvis å legge til prop-en får dusinvis av advarsler til å forsvinne, er det en grunn til å undersøke videre, ikke et tegn på at det underliggende problemet er løst.
Steg 8: Verifiser fiksen i utviklings- og produksjonsmiljø
AI-generert illustrasjon: Etter å ha endret koden, verifiser en ren omlasting, korrekt interaktivitet og en produksjonsbygging i stedet for å stole kun på utviklingsoverlayen. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
Utviklingsatferd kan avvike fra en optimalisert produksjonsbygging. Etter at feilen er borte lokalt, utfør en produksjonsstil-sjekk for rammeverket ditt. For et typisk Next.js-prosjekt betyr det ofte å bygge og starte applikasjonen med dine normale pakkebehandlerkommandoer, og deretter gjøre nye navigasjoner og omlastinger.
Sjekk
Godt tegn
Hvis den feiler
Ny omlasting
Ingen hydreringsfeil i konsollen
Sjekk på nytt den tidligste avvikende komponenten
Innledende visuell tilstand
Ingen utilsiktet blink eller erstatning
Gjør starttilstanden deterministisk
Interaksjoner
Knapper, skjemaer, menyer og state fungerer normalt
Bekreft at komponenten fortsatt hydrerer og hendelsesbehandlere festes
Produksjonsbygging
Samme korrekte resultat som i utvikling
Undersøk produksjonskun data, CDN, CSS eller optimaliseringsatferd
Utvidelser deaktivert
Resultatet er uendret
Identifiser DOM-endrende utvidelsesatferd
Hvis du direkte eier React SSR-inngangspunktet i stedet for å bruke et rammeverk, støtter hydrateRoot også feilkallbakker som onRecoverableError, som kan hjelpe produksjonslogging. Rammeverkbrukere bør generelt ikke erstatte rammeverkets hydreringsinngangspunkt kun for å legge til tilpasset håndtering.
Når du bør prøve en annen gjengivelsesstrategi
AI-generert illustrasjon: Endre strategi når en komponent fundamentalt ikke kan produsere meningsfull server-HTML, men hold den klientavhengige grensen så liten som praktisk. Dette er ikke et faktisk skjermbilde fra nettleser, React eller Next.js; bruk de verifiserte kode- og dokumentasjonslenkene i artikkelen som kilde til sannhet.
I noen tilfeller er den beste fiksen ikke å tvinge en komponent inn i SSR. Vurder en annen gjengivelsesstrategi når:
Komponenten er bygget rundt window, canvas, WebGL, nettlesermålinger eller et annet nettleseravhengig API.
En tredjeparts-widget støtter offisielt ikke SSR.
Komponentens meningsfulle innhold avhenger helt av enhetslokal state som localStorage.
Sanntidsdata endres så raskt at det å matche et serverøyeblikksbilde har liten verdi.
I disse tilfellene kan en målrettet klientavhengig grense være renere. Nøkkelordet er målrettet. Å deaktivere SSR for en hel side for å akkommodere ett diagram eller en editor kan unnvære nyttig servergjengitt innhold, lasteadferd og andre fordeler unødvendig.
Vanlige fikser som ser vellykkede ut, men ikke er det
Snarvei
Hvorfor den er ufullstendig
Better kriterium
Legg til 'use client' overalt
Client Components kan fortsatt forhåndsgjengis i Next.js
Flytt nettleseravhengig logikk etter hydrering eller isoler den bevisst
Pakk gjengivelseslogikk inn i typeof window !== 'undefined'
Grenen i seg selv kan skape ulik første-gjengivelse markup
Hold den første gjengivelsen identisk
Bruk suppressHydrationWarning bredt
Det skjuler en advarsel i stedet for å gjenopprette applikasjonstilstand
Bruk kun for et forventet, lokalt, uunngåelig avvik
Deaktiver SSR for hele siden
Det kan fjerne symptomet ved å fjerne hydrering for for mye UI
Bruk den minste praktiske klientavhengige grensen
Test kun klient-side navigasjon
Et avvik kan dukke opp kun ved en direkte forespørsel eller hard omlasting
Test ferske servergjengitte sideinnlastinger
Grensene for disse fiksene
En hydreringsfeil forteller deg at server- og klientgjengivelse divergerte; den beviser ikke hvorfor. Det samme symptomet kan komme fra applikasjonslogikk, nettleserendring, et bibliotek, en CDN, feilformet HTML eller endrede data. Det finnes ikke én enkelt kodebit som trygt fikser alle disse tilfellene.
Videre, å fjerne hydreringsadvarsler garanterer ikke korrekthet andre steder. En klientavhengig komponent kan fortsatt ha datakappløp. En deterministisk første gjengivelse kan fortsatt vise utdaterte data etter hydrering. En gyldig DOM kan fortsatt inneholde tilgjengelighetsproblemer. Behandle hydrering som én kvalitetsport, ikke den eneste.
Reacts 19.3s nye browser-API betyr heller ikke at alle rammeverk umiddelbart bør erstatte sine etablerte nettleseravhengige mønstre. Rammeverkintegrasjon og installerte versjoner betyr noe. Hvis prosjektet ditt er på en eldre React- eller Next.js-utgivelse, følg dokumentasjonen for den utgivelsen i stedet for å kopiere en nyere API blindt.
En pålitelig beslutningsrekkefølge
Finn den minste komponenten som avviker.
Sjekk etter endrede verdier som datoer, tilfeldige tall, lokalformatering og data hentet to ganger.
Fjern nettleseravhengige API-er fra den første serverkompatible gjengivelsen.
Sørg for at serveren og den første klientgjengivelsen bruker samme dataøyeblikksbilde.
Valider HTML-strukturen.
Utelukk utvidelser, CSS-in-JS SSR-konfigurasjon og CDN/Edge-omskriving.
Bruk en Effect, målrettet klientavhengig gjengivelse eller React 19.3 use(browser()) kun når innholdet genuint avhenger av nettleseren.
Reserver suppressHydrationWarning for små, tilsiktede avvik.
Verifiser med en ny omlasting og en produksjonsbygging.
Den varige fiksen er ikke "få React til å slutte å klage". Det er å gjøre den innledende gjengivelseskontrakten eksplisitt: serveren og nettleseren bør være enige om det første brukergrensesnittet, eller den nettleseravhengige seksjonen bør være bevisst isolert slik at React ikke blir bedt om å hydrere markup som aldri kunne samsvart.