Hvernig á að laga villuna „Hydration failed because the initial UI does not match“

Markmiðið er einfalt að lýsa: HTML-ið sem er framleitt á servernum verður að passa við það sem React framleiðir við fyrstu teikningu í vafranum. Þegar svo er, getur React tengt atburðarhöndlara og gert síðuna gagnvirka án þess að kasta hydration mismatch villu, skipta undirtré eða sýna óvænta sjónræna stökk.

Hydration er ferlið þar sem React tekur HTML sem hefur þegar verið teiknað á servernum og tengir React hegðun við það í vafranum. Núverandi hydrateRoot skjölun React segir að búast megi við að efnið sem teiknað er á clientnum sé eins og efnið sem teiknað er á servernum og að mismunur eigi að vera meðhöndlaður sem villur.

Nákvæm orðalag villunnar hefur breyst í gegnum React og framework útgáfur. Þú gætir séð eldri skilaboð eins og "Hydration failed because the initial UI does not match what was rendered on the server", eða nýrri skilaboð sem útskýra að server-rendered tréð hafi ekki passað við clientinn. Aðferðafræðin við villusögnun er sú sama.

Útgáfuupplýsingar skipta máli. Frá og með 11. september 2026, listar opinbera React síðan React 19.3 sem nýjustu React útgáfuna, en núverandi Next.js skjölunin nefnir Next.js 16.3.4 sem nýjustu Next.js útgáfuna. Athugaðu React útgáfusíðuna og núverandi Next.js skjölunina ef þú lest þetta síðar, því tiltækar API og villuskilaboð geta breyst.

Hvað telst sem vel heppnuð lagfæring?

Metaðu ekki velgengni eingöngu út frá því hvort rauður development overlay hverfi. Góð lagfæring ætti að uppfylla nokkrar athuganir:

• Hydration viðvörunin eða villan birtist ekki lengur við hreina endurhleðslu.
• Upprunalega server-rendered UI-ið og fyrsta React teikningin í vafranum tákna sama efni og sömu uppbyggingu.
• Viðkomandi íhlutur helst gagnvirkur eftir hydration.
• Það er engin augljós blik frá einu gildi í annað nema sú breyting sé ásetningsbundin og hönnuð.
• Vandamálið helst lagað í production build, ekki bara í development server.
• Þú hefur leiðrétt orsökina frekar en að fela raunverulegan mismun með valkosti til að þagga niður í viðvörunum.

Ef viðvörunin hverfur en síðan teiknar nú mikilvægt efni aðeins eftir að JavaScript hleðst, gæti villan verið horfin en notendaupplifunin versnað. Það getur verið sanngjarnt viðskipti fyrir vafra-eina widget, en það er ekki sjálfkrafa besta niðurstaðan fyrir aðalefni síðunnar.

Skref 1: Endurskapa mismuninn og finna minnsta bilandi íhlutinn

Byrjaðu á harðri endurhleðslu í development og lestu alla villuna, að meðtöldi component stack. Skráðar hydration villur React 19 nefna nokkrar algengar orsakir: server/client greinar eins og typeof window !== 'undefined', breytileg gildi eins og Date.now() eða Math.random(), staðbundin dagsetningarsnið, ytri gögn sem breyttust án snapshot, ógilt HTML nesting, og vafra viðbætur sem breyta DOM. Sjá React villu 418.

Next.js gefur svipaða lista í opinberri hydration villuleiðbeiningu sinni, og bætir við vafra-eina API eins og window og localStorage, CSS-in-JS stillingar, og HTML sem breytt er af Edge/CDN lagi.

Praktísk aðferð til að einangra vandamálið er að tímabundið skipta út grunuðum dynamic hlutum fyrir ákveðinn texta. Ef villan hverfur, endurheimtu þessa hluta einn í einu. Þetta er yfirleitt hraðara en að breyta global rendering stillingum áður en þú veist hvaða íhlutur er ábyrgur.

Gæðamerki

Þú ert tilbúinn að halda áfram þegar þú getur nefnt bæði bilandi íhlutinn og gildið eða uppbygginguna sem er ólík. „Það gerist einhvers staðar í dashboard“ er enn of vítt. „Tímaskráningin í StatusCard er framleidd óháð á servernum og clientnum“ er aðgerðarhæft.

Skref 2: Fjarlægðu óákveðin gildi úr fyrstu teikningunni

Ákveðin teikning (deterministic rendering) þýðir að sömu inntök framleiða sama upphafs UI. Gildi sem breytast óháð á milli server teikningar og vafra teikningar eru algengar mismun orsakir.

Hugsaðu um þetta vandamálsmynstur:

export default function LastUpdated() {
  return <time>{new Date().toLocaleString()}</time>;
}

Serverinn og vafrið geta keyrt þennan kóða á mismunandi tímum og í mismunandi staðbundnum stillingum eða tímabeltum. Betri lausn fer eftir því hvað síðan er ætlað að miðla.

Ef tímaskráningin táknar server gögn, reiknaðu eða sækðu það einu sinni á servernum og sendu sama serialized gildi til clients:

export default function LastUpdated({ isoTime }) {
  return <time dateTime={isoTime}>{isoTime}</time>;
}

Ef gildið raunverulega fer eftir vafra notandans, teiknaðu stöðugt placeholder fyrst og uppfærðu það eftir hydration.

'use client';

import { useEffect, useState } from 'react';

export default function LocalTime() {
  const [text, setText] = useState('Loading local time...');

  useEffect(() => {
    setText(new Date().toLocaleString());
  }, []);

  return <time>{text}</time>;
}

Þetta virkar vegna þess að serverinn og fyrsta client teikningin framleiða báðir sama placeholder. useEffect skjölun React lýsir þessu tveggja þrepa mynstri fyrir sjaldgæf tilfell þar sem client efni verður að vera ólíkt server efni.

Hvenær á að breyta aðferð

Ef vafra-eina gildið er allt tilgangur íhlutarins – til dæmis ritill endurheimtur úr localStorage eða widget sem getur ekki teiknað merkingarbært efni á servernum – getur þvingun á placeholder-and-effect mynstri í gegnum allan íhlutinn bætt við óþarfa flóknum. Í því tilviki, notaðu ásetningsbundna vafra-eina mörk frekar en að láta sem íhluturinn sé server-renderable.

Skref 3: Ekki lesa vafra-eina API við fyrstu server-samhæfa teikningu

Algeng misskilningur í Next.js er að bæta við 'use client' tryggi að íhluturinn teiknist aðeins í vafranum. Það gerir það ekki. Next.js útskýrir að Client Components séu mörkin fyrir state, effects, event handlers og vafra API, en Client Components geta samt tekið þátt í prerendering. Sjá núverandi use client skjölunina.

Þetta mynstur er áhættusamt við teikningu:

'use client';

export default function ThemeLabel() {
  const theme = localStorage.getItem('theme') ?? 'light';
  return <span>{theme}</span>;
}

Á servernum, localStorage er ekki til. Jafnvel grein eins og typeof window !== 'undefined' getur framleitt mismunandi markup við fyrstu vafra teikningu, sem React og Next.js bæði skrá sem orsök hydration mismatches.

Fyrir litla mismun, færa vafra lesturinn í Effect. Fyrir íhlut sem ætti raunverulega að vera vafra-einn í Next.js, getur þú hlaðið hann dynamic með SSR slökkt:

'use client';

import dynamic from 'next/dynamic';

const BrowserOnlyChart = dynamic(
  () => import('./BrowserOnlyChart'),
  { ssr: false }
);

export default function Dashboard() {
  return <BrowserOnlyChart />;
}

Next.js skráir ssr: false fyrir Client Components í lazy loading leiðbeiningu sinni. Sama leiðbeining segir að ssr: false sé ekki stutt þegar þú reynir að nota þann valkost beint í Server Component; færa dynamic importinn inn í Client Component.

React 19.3: fyrsta flokks vafra-einn valkostur

React 19.3 kynnti browser API. Íhlutur getur kallað use(browser()) inni í Suspense mörkum til að velja íhlutinn úr server rendering. Serverinn teiknar Suspense fallback, en íhluturinn teiknar eðlilega í vafranum. Sjá browser API tilvísun React.

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>
  );
}

Í React Server Components forriti, segir React að use(browser()) verði að vera kallað frá Client Component. Staðfestu einnig að framework þitt og uppsett React útgáfa birti þetta API áður en þú tekur það í notkun.

Skref 4: Gerðu Server gögn og fyrstu Client gögn sama Snapshot

Snapshot er nákvæmlega gildisástandið sem notað er til að framleiða upphafs HTML. Hydration verður viðkvæmt ef serverinn teiknar eina gildisútgáfu og clientinn les strax nýrri eða öðruvísi raðaðri útgáfu áður en hydration lýkur.

Til dæmis, ímyndaðu þér að serverinn teikni verð $99, en clientinn sækji strax sama vöru og fái $109 áður en fyrsta teikning. Vandamálið er ekki að gögnin hafi breyst; breytileg gögn eru eðlileg. Vandamálið er að umhverfin tvö notuðu mismunandi upphafsinntök.

Öruggt mynstur er:

1. Sækja upphafsgögn á servernum.
2. Teikna HTML-ið frá þeim gögnum.
3. Senda eða serialize sama upphafsgögn til client íhlutarins.
4. Eftir hydration, leyfa clientnum að revalidate og uppfæra ef nýrri gögn eru til staðar.

Rétt útfærsla fer eftir data-fetching líkani framework þíns, en gæðakröfan helst sú sama: server HTML-ið og fyrsta client tréð ættu að byggja á sama rökfræðilega ástandi.

Hvenær á að breyta aðferð

Ef efnið er eðlilega rauntíma og gamalt server snapshot myndi villa notendur – til dæmis live trading widget eða hratt breytilegt operations console – íhugaðu að teikna stöðugt shell á servernum og hlaða live hlutanum á clientnum. Það gefur upp eitthvað server-rendered efni fyrir það svæði, en það gæti verið heiðarlegra en að hydrate gegnum gögn sem eru tryggð að breytast.

Skref 5: Lagaðu ógilt HTML áður en þú kærir React

Vafrar eru leyfðir að leiðrétta rangt formuð eða ógilt nesting HTML. Sú leiðrétting getur framleitt DOM uppbyggingu sem er ólík þeirri uppbyggingu React búist við, jafnvel þótt JSX-ið hafi litið sjónrænt plausibelt út.

Next.js nefnir sérstaklega dæmi eins og <div> inni í <p>, lista inni í málsgrein, innri tengla (nested anchors), og innri hnappa (nested buttons) sem orsakir hydration vandamála.

Til dæmis, forðastu:

<p>
  Intro text
  <div>Details</div>
</p>

Notaðu gilt uppbyggingu í staðinn:

<div>
  <p>Intro text</p>
  <div>Details</div>
</div>

Ef íhlutabókasafn framleiðir markup-ið, skoðaðu lokalegu DOM-ið frekar en að gera ráð fyrir að wrapper elements séu gild. Lint rule eða HTML validator getur hjálpað, en raunverulegt DOM vafrians er það sem React hydrate.

Skref 6: Útiloka kóða utan íhlutarins

Ef teikningarlogík þín er ákveðin og HTML-ið þitt er gilt, athugaðu hvort eitthvað breyti server HTML-i áður en React hydrate það.

Opinber Next.js skjölun nefnir nokkrar möguleikar:

• Vafra viðbót breytir síðunni áður en React hleðst.
• CSS-in-JS bókasafn er rangt stillt fyrir server rendering.
• Edge eða CDN eiginleiki endurskrifar eða minnkar HTML svarið.
• Á iOS, sjálfvirk greining á símanúmerum, netföngum, dagsetningum eða heimilisfangum getur breytt texta í tengla í sumum tilfellum.

Notaðu stýrðar samanburðir. Prófaðu í einkavafra glugga með viðbætur slökktar. Ef villan kemur fram aðeins á bakvið CDN, berðu saman við origin response. Ef hún byrjaði eftir að þú tókst í notkun styling bókasafn, fylgdu opinberri SSR stillingu bókasafnsins frekar en að beita almennri hydration workaround.

Gæðamerki

Þú hefur einangrað þessa flokk vandamála þegar sama application build hydrateast rétt í einu stýrðu umhverfi en bilast eftir að tiltekin vafra viðbót, proxy, CDN umbreyting eða samþætting breytir HTML-i.

Skref 7: Notaðu suppressHydrationWarning aðeins fyrir raunverulega óforðanlegan staðbundinn mismun

React veitir suppressHydrationWarning={true} fyrir sjaldgæf tilfell þar sem texti eða attributes eins elements getur ekki sanngjarnt passa saman, eins og ákveðnar tímaskráningar.

<time suppressHydrationWarning>
  {new Date().toLocaleString()}
</time>

Þetta er ekki almenn lagfæringerfð. common DOM props skjölun React segir að valkosturinn virki aðeins eitt lag djúpt og sé ætlað sem escape hatch. Next.js hydration leiðbeiningin varar einnig við að React muni ekki reyna að lappa upp mismunandi textainnihald þegar þessi valkostur er notaður.

Notaðu það aðeins þegar allt þetta er satt:

• Mismunurinn er búist við og staðbundinn.
• Mismunurinn táknar ekki rangt application state.
• Uppbyggingin í kring er stöðug.
• Þú hefur meðvitað tekið við að upphaflegt server gildi og vafra gildi séu ólík.

Ef að bæta við propnum fær tugina viðvörunum til að hverfa, er það ástæða til að rannsaka frekar, ekki merki um að undirliggjandi vandamálið sé leyst.

Skref 8: Staðfestu lagfæringuna í Development og Production

Development hegðun getur verið ólík optimized production build. Eftir að villan er horfin staðbundið, framkvæmdu production-style athugun fyrir framework þitt. Fyrir typical Next.js project, þýðir það oft að builda og ræsa forritinu með venjulegum package-manager skipunum, og síðan framkvæma ferskar navigations og endurhleðslur.

Notaðu þessa staðfestingar checklist:

Ef þú átt beint React SSR entry point frekar en að nota framework, styður hydrateRoot einnig error callbacks eins og onRecoverableError, sem getur hjálpað production logging. Framework notendur ættu almennt ekki að skipta út hydration entry point frameworkins bara til að bæta við custom handling.

Hvenær á að prófa aðra rendering strategy

Stundum er besta lagfæringin ekki að þvinga íhlut í SSR. Íhugaðu aðra rendering strategy þegar:

• Íhluturinn er byggður í kringum window, canvas, WebGL, vafra mælingar eða annað vafra-eint API.
• Þriðja aðila widget styður opinberlega ekki SSR.
• Merkingarbært efni íhlutarins fer alfarið eftir device-local state eins og localStorage.
• Rauntíma gögn breytast svo hratt að að passa við server snapshot hefur lítið gildi.

Í þeim tilfellum, getur markviss client-ein mörk verið hreinari. Lykilorðið er markviss. Að slökkva á SSR fyrir alla síðu til að koma til móts við einn chart eða ritil getur fórnað gagnlegu server-rendered efni, loading hegðun og öðrum ávinningi óþarflega.

Algengar lagfæringar sem líta út fyrir að vera vel heppnaðar en eru ekki

Takmarkanir þessara lagfæringa

Hydration villa segir þér að server og client teikning hafi diverged; það sannar ekki af hverju. Sama einkennið getur komið frá application logík, vafra breytingu, bókasafni, CDN, rangt formuðu HTML eða breytilegum gögnum. Það er engin ein kóðasegment sem lagar öll þessi tilfell örugglega.

Einnig, að fjarlægja hydration viðvaranir tryggir ekki réttleika annars staðar. Client-einn íhlutur getur samt haft data races. Ákveðin fyrsta teikning getur samt sýnt gömul gögn eftir hydration. Gilt DOM getur samt innihaldið accessibility vandamál. Meðhöndla hydration sem eitt gæðagátt, ekki eina.

Nýja browser API React 19.3 þýðir heldur ekki að hvert framework ætti strax að skipta út sinni stofnaðri vafra-einu mynstri. Framework samþætting og uppsettar útgáfur skipta máli. Ef verkefnið þitt er á eldri React eða Next.js útgáfu, fylgdu skjöluninni fyrir þá útgáfu frekar en að afrita nýrra API blindlega.

Áreiðanleg ákvörðunar röð

1. Finna minnsta íhlutinn sem mismunar.
2. Athuga fyrir breytilegum gildum eins og dagsetningum, slembitölum, staðbundnu sniði og gögnum sóttum tvisvar.
3. Fjarlægja vafra-eina API úr fyrstu server-samhæfu teikningunni.
4. Tryggja að server og fyrsta client teikning noti sama gildis snapshot.
5. Staðfesta HTML uppbyggingu.
6. Útiloka viðbætur, CSS-in-JS SSR stillingar og CDN/Edge endurskrift.
7. Nota Effect, markvissa client-eina rendering eða React 19.3 use(browser()) aðeins þegar efnið raunverulega fer eftir vafranum.
8. Varðveita suppressHydrationWarning fyrir litla, ásetningsbundna mismuna.
9. Staðfesta með ferskri endurhleðslu og production build.

Varanlega lagfæringin er ekki „að fá React til að hætta að kvarta“. Það er að gera upphafs teikningarsamninginn skýran: serverinn og vafrið ættu að vera sammála um fyrsta UI, eða vafra-eini hlutinn ætti að vera ásetningsbundið einangraður svo React sé ekki beðið um að hydrate markup sem gæti aldrei passað.