Kuinka korjata virhe: Hydration failed because the initial UI does not match

Tavoitteesi on helppo kuvata: palvelimella tuotetun HTML:n on vastattava sitä, mitä React tuottaa selaimen ensimmäisessä renderöinnissä. Kun näin on, React voi liittää tapahtumankäsittelijät ja tehdä sivusta interaktiivisen heittämättä hydraatiovirhettä, korvaamatta alipuu tai näyttämättä odottamatonta visuaalista hyppyä.

Hydraatio on prosessi, jossa React ottaa HTML:n, joka on jo renderöity palvelimella, ja liittää siihen Reactin toiminnallisuuden selaimessa. Reactin nykyinen hydrateRoot-dokumentaatio sanoo, että asiakaspuolen renderöidyn sisällön odotetaan olevan identtinen palvelinpuolen renderöidyn sisällön kanssa ja että epäsuhtia tulisi pitää bugeina.

Virheen tarkka sanamuoto on muuttunut Reactin ja framework-versioiden myötä. Saatatat nähdä vanhemman viestin, kuten "Hydration failed because the initial UI does not match what was rendered on the server", tai uudemman viestin, joka selittää, että palvelinpuolen renderöity puu ei vastannut asiakaspuolen puuta. Vianjäljityksen periaate on sama.

Versioyhteys on tärkeä. 11. syyskuuta 2026 mennessä virallinen React-sivusto listaa React 19.3:n viimeisimmäksi React-versioksi, kun taas nykyinen Next.js-dokumentaatio tunnistaa Next.js 16.3.4:n viimeisimmäksi Next.js-julkaisuksi. Tarkista Reactin versiosivulta ja nykyisestä Next.js-dokumentaatiosta, jos luet tätä myöhemmin, koska käytettävissä olevat API:t ja virheilmoitukset voivat muuttua.

Mikä lasketaan onnistuneeksi korjaukseksi?

Älä arvioi onnistumista vain sen perusteella, katoaako punainen kehitysympäristön päällekkäinen näyttö. Hyvän korjauksen tulisi täyttää useita tarkistuksia:

• Hydraatiovaroitus tai -virhe ei enää näy puhtaalla uudelleenlatauksella.
• Alkuperäinen palvelinrenderöity käyttöliittymä ja selaimen ensimmäinen React-renderöinti esittävät samaa sisältöä ja rakennetta.
• Kärsinyt komponentti pysyy interaktiivisena hydraation jälkeen.
• Ei ole ilmeistä välähdystä yhdestä arvosta toiseen, ellei muutos ole tarkoituksellinen ja suunniteltu.
• Ongelma pysyy korjattuna tuotantoversiossa, ei vain kehityspalvelimella.
• Olet korjannut syyn sen sijaan, että olisit piilottanut todellisen epäsuhtan varoituksen vaimennusvaihtoehdolla.

Jos varoitus katoaa, mutta sivu renderöi nyt tärkeän sisällön vasta JavaScriptin latauduttua, virhe voi olla poissa, mutta käyttäjäkokemus on huonontunut. Se voi olla kohtuullinen kompromissi pelkälle selainwidgetille, mutta se ei automaattisesti ole paras tulos sivun pääsisällölle.

Vaihe 1: Toista epäsuhta ja löydä pienin epäonnistuva komponentti

Aloita pakotetulla uudelleenlatauksella kehitysympäristössä ja lue koko virhe, mukaan lukien komponenttipino. React 19:n dokumentoitu hydraatiovirhe listaa useita yleisiä syitä: palvelin/asiakas-haarat, kuten typeof window !== 'undefined', muuttuvat arvot, kuten Date.now() tai Math.random(), alueasetuksista riippuva päivämäärämuotoilu, ulkoinen data, joka on muuttunut ilman snapshotia, virheellinen HTML-pesäkkäisyys ja DOM:ia muuttavat selainlaajennukset. Katso React-virhe 418.

Next.js antaa vastaavan luettelon virallisessa hydraatiovirheoppaassaan, lisäten selain-API:t, kuten window ja localStorage, CSS-in-JS-määritykset ja Edge/CDN-kerroksen muuttaman HTML:n.

Käytännön eristysmenetelmä on korvata väliaikaisesti epäillyt dynaamiset osat deterministisellä tekstillä. Jos virhe katoaa, palauta osat yksi kerrallaan. Tämä on yleensä nopeampaa kuin globaalien renderöintiasetusten muuttaminen ennen kuin tiedät, mikä komponentti on vastuussa.

Laatumerkki

Olet valmis siirtymään eteenpäin, kun voit nimetä sekä epäonnistuvan komponentin että arvon tai rakenteen, joka eroaa. "Se tapahtuu jossain kojelaudassa" on edelleen liian laaja. "StatusCardin aikaleima tuotetaan itsenäisesti palvelimella ja asiakkaalla" on toimiva.

Vaihe 2: Poista ei-deterministiset arvot alkuperäisestä renderöinnistä

Deterministinen renderöinti tarkoittaa, että samat syötteet tuottavat saman alkukäyttöliittymän. Arvot, jotka muuttuvat itsenäisesti palvelin- ja selainrenderöinnin välillä, ovat yleisiä epäsuhteen lähteitä.

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

Palvelin ja selain voivat suorittaa tämän koodin eri hetkinä ja eri alueasetuksissa tai aikavyöhykkeillä. Parempi ratkaisu riippuu siitä, mitä sivun on tarkoitus viestiä.

Jos aikaleima edustaa palvelindataa, laske tai hae se kerran palvelimella ja välitä sama serialisoitu arvo asiakkaalle:

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

Jos arvo todella riippuu käyttäjän selaimesta, renderöi ensin vakaa paikkamerkki ja päivitä se hydraation jälkeen.

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

Tämä toimii, koska palvelin ja ensimmäinen asiakasrenderöinti tuottavat molemmat saman paikkamerkin. Reactin useEffect-dokumentaatio kuvaa tämän kaksivaiheisen kuvion harvinaisissa tapauksissa, joissa asiakassisällön on erottava palvelinsisällöstä.

Milloin vaihtaa lähestymistapaa

Jos selainkohtainen arvo on komponentin koko tarkoitus – esimerkiksi localStorage:sta palautettu editori tai widget, jota ei voi merkityksellisesti renderöidä palvelimella – paikkamerkki- ja effect-kuvion pakottaminen koko komponenttiin voi lisätä tarpeetonta monimutkaisuutta. Tässä tapauksessa käytä tarkoituksellista selainrajaa sen sijaan, että teeskentelisit komponentin olevan palvelinrenderöitävä.

Vaihe 3: Älä lue selain-API:ita ensimmäisen palvelinyhteensopivan renderöinnin aikana

Yleinen väärinkäsitys Next.js:ssä on, että 'use client':n lisääminen takaa, että komponentti renderöityy vain selaimessa. Näin ei ole. Next.js selittää, että Client Components ovat raja tilalle, effecteille, tapahtumankäsittelijöille ja selain-API:ille, mutta Client Components voivat silti osallistua esirenderöintiin. Katso nykyinen use client -dokumentaatio.

Tämä kuvio on riskialtis renderöinnin aikana:

'use client';

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

Palvelimella localStorage ei ole olemassa. Jopa haara, kuten typeof window !== 'undefined', voi tuottaa eri merkinnän ensimmäisessä selainrenderöinnissä, mikä on sekä Reactin että Next.js:n dokumentoima hydraatioepäsuhteen syy.

Pienissä eroissa siirrä selaimen luku Effectiin. Komponentille, jonka tulisi todella olla vain selainkäyttöinen Next.js:ssä, voit ladata sen dynaamisesti SSR:n ollessa poissa käytöstä:

'use client';

import dynamic from 'next/dynamic';

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

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

Next.js dokumentoi ssr: false:n Client Components -komponenteille laatakkaislatausoppaassaan. Sama opas toteaa, että ssr: false ei ole tuettu, kun yrität käyttää tätä vaihtoehtoa suoraan Server Component -komponentissa; siirrä dynaaminen import Client Component -komponenttiin.

React 19.3: ensiluokkainen vain-selain-vaihtoehto

React 19.3 esitteli browser-API:n. Komponentti voi kutsua use(browser()):ta Suspense-rajan sisällä poistaakseen kyseisen komponentin palvelinrenderöinnistä. Palvelin renderöi Suspense-paikkamerkin, kun taas komponentti renderöityy normaalisti selaimessa. Katso Reactin browser API -viite.

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 -sovelluksessa React sanoo, että use(browser()):ta on kutsuttava Client Component -komponentista. Varmista myös, että frameworkisi ja asennettu React-versio tarjoavat tämän API:n ennen sen käyttöönottoa.

Vaihe 4: Tee palvelindatasta ja ensimmäisestä asiakasdatasta sama tilannekuva

Tilannekuva on tarkka data-tila, jota käytettiin alkuperäisen HTML:n tuottamiseen. Hydraatio haurastuu, jos palvelin renderöi yhden dataversio ja asiakas lukee välittömästi uudemman tai eri järjestyksessä olevan version ennen hydraation valmistumista.

Oletetaan esimerkiksi, että palvelin renderöi hinnan 99 dollaria, mutta asiakas hakee välittömästi saman tuotteen ja saa 109 dollaria ennen ensimmäistä renderöintiään. Ongelma ei ole siinä, että data muuttui; datan muuttuminen on normaalia. Ongelma on siinä, että kaksi ympäristöä käyttivät eri alkusyötteitä.

Vahva kuvio on:

1. Hae alkudata palvelimella.
2. Renderöi HTML tuosta datasta.
3. Välitä tai serialisoi sama alkudata asiakaskomponenttiin.
4. Salli asiakkaan uudelleenvalidoida ja päivittää hydraation jälkeen, jos uudempi data on olemassa.

Oikea toteutus riippuu frameworkisi datahaumallista, mutta laatuvaatimus pysyy samana: palvelin-HTML:n ja ensimmäisen asiakaspuun tulisi perustua samaan loogiseen tilaan.

Milloin vaihtaa lähestymistapaa

Jos sisältö on luonnostaan reaaliaikaista ja vanhentunut palvelintilannekuva harhauttaisi käyttäjiä – esimerkiksi live-kaupankäyntiwidget tai nopeasti muuttuva operaatiokonsoli – harkitse vakaan kuoren renderöintiä palvelimella ja live-osan lataamista asiakkaalla. Se luopuu jostakin palvelinrenderöidystä sisällöstä tälle alueelle, mutta se voi olla rehellisempää kuin hydraatio dataa vasten, jonka on taattu muuttuvan.

Vaihe 5: Korjaa virheellinen HTML ennen kuin syytät Reactia

Selaimet saavat korjata virheellisesti muotoiltua tai virheellisesti pesäkkäistä HTML:ää. Tämä korjaus voi tuottaa DOM-rakenteen, joka eroaa siitä, mitä React odottaa, vaikka JSX näytti visuaalisesti uskottavalta.

Next.js listaa nimenomaisesti esimerkkejä, kuten <div>:n <p>:n sisällä, listan kappaleen sisällä, pesäkkäiset ankkurit ja pesäkkäiset painikkeet hydraatio-ongelmien syinä.

Vältä esimerkiksi:

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

Käytä sen sijaan kelvollista rakennetta:

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

Jos komponenttikirjasto generoi merkinnän, tutki lopullista DOM:ia sen sijaan, että olettaisit peittäväisten elementtien olevan kelvollisia. Lint-sääntö tai HTML-validaattori voi auttaa, mutta selaimen todellinen DOM on se, mitä React hydraatoi.

Vaihe 6: Sulje pois komponentin ulkopuolinen koodi

Jos renderöintilogiikkasi on deterministinen ja HTML:si on kelvollinen, tarkista, muuttaako jokin palvelin-HTML:ää ennen kuin React hydraatoi sen.

Virallinen Next.js-dokumentaatio nimeää useita mahdollisuuksia:

• Selainlaajennus muuttaa sivua ennen Reactin latautumista.
• CSS-in-JS-kirjasto on määritetty virheellisesti palvelinrenderöintiä varten.
• Edge- tai CDN-ominaisuus kirjoittaa uudelleen tai pienentää HTML-vastausta.
• iOS:ssä puhelinnumeroiden, sähköpostiosoitteiden, päivämäärien tai osoitteiden automaattinen tunnistus voi muuttaa tekstin linkeiksi joissakin tapauksissa.

Käytä hallittuja vertailuja. Testaa yksityisessä selainikkunassa, jossa laajennukset on poistettu käytöstä. Jos virhe esiintyy vain CDN:n takana, vertaa alkuperäiseen vastaukseen. Jos se alkoi tyylikirjaston käyttöönoton jälkeen, seuraa kyseisen kirjaston virallista SSR-määritystä sen sijaan, että soveltaisit yleistä hydraatiokorjausta.

Laatumerkki

Olet eristänyt tämän luokan ongelman, kun sama sovellusversio hydrautuu oikein yhdessä hallitussa ympäristössä, mutta epäonnistuu, kun tietty selainlaajennus, välityspalvelin, CDN-muunnos tai integraatio muuttaa HTML:ää.

Vaihe 7: Käytä suppressHydrationWarningia vain todelliseen väistämättömään paikalliseen eroon

React tarjoaa suppressHydrationWarning={true}:n harvinaisiin tapauksiin, joissa yksittäisen elementin teksti tai attribuutit eivät kohtuudella voi vastata toisiaan, kuten tietyt aikaleimat.

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

Tämä ei ole yleinen korjausmekanismi. Reactin yleiset DOM-ominaisuudet -dokumentaatio sanoo, että vaihtoehto toimii vain yhden tason syvyyteen ja on tarkoitettu pakoaukoksi. Next.js:n hydraatioopas varoittaa myös, että React ei yritä korjata epäyhdenmukaista tekstisisältöä, kun tätä vaihtoehtoa käytetään.

Käytä sitä vain, kun kaikki nämä ovat totta:

• Ero on odotettu ja paikallinen.
• Epäsuhta ei edusta virheellistä sovellustilaa.
• Ympäröivä rakenne on vakaa.
• Olet tietoisesti hyväksynyt, että alkuperäinen palvelinarvo ja selaimen arvo eroavat.

Jos ominaisuuden lisääminen saa kymmenet varoitukset katoamaan, se on syy tutkia asiaa tarkemmin, ei merkki siitä, että perusongelma on ratkaistu.

Vaihe 8: Varmista korjaus kehitys- ja tuotantoympäristössä

Kehitysympäristön käyttäytyminen voi erota optimoidusta tuotantoversiosta. Kun virhe on poissa paikallisesti, suorita tuotantotyypin tarkistus frameworkillesi. Tyypillisessä Next.js-projektissa se tarkoittaa usein sovelluksen kääntämistä ja käynnistämistä normaaleilla pakettienhallintakomennoilla, minkä jälkeen tehdään uusia navigointeja ja uudelleenlatauksia.

Käytä tätä varmistuslista:

Jos omistat React SSR:n sisääntulopisteen suoraan sen sijaan, että käyttäisit frameworkia, hydrateRoot tukee myös virhecallbackeja, kuten onRecoverableError, jotka voivat auttaa tuotantolokituksessa. Framework-käyttäjien ei yleensä tulisi korvata frameworkin hydraatiosisääntuloa vain lisätäkseen mukautettua käsittelyä.

Milloin kokeilla eri renderöintistrategiaa

Joskus paras korjaus ei ole pakottaa komponenttia SSR:ään. Harkitse eri renderöintistrategiaa, kun:

• Komponentti on rakennettu window:n, canvasin, WebGL:n, selainmittausten tai muun selain-API:n ympärille.
• Kolmannen osapuolen widget ei virallisesti tue SSR:ää.
• Komponentin merkityksellinen sisältö riippuu kokonaan laitteessa paikallisesta tilasta, kuten localStorage:sta.
• Reaaliaikainen data muuttuu niin nopeasti, että palvelintilannekuvan sovittaminen on vähäarvoista.

Näissä tapauksissa kohdennettu vain-asiakasraja voi olla puhtaampi. Avainsana on kohdennettu. SSR:n poistaminen käytöstä koko sivulta yhden kaavion tai editorin vuoksi voi tarpeettomasti uhraata hyödyllistä palvelinrenderöityä sisältöä, latautumiskäyttäytymistä ja muita etuja.

Yleiset korjaukset, jotka näyttävät onnistuneilta mutta eivät ole

Näiden korjausten rajat

Hydraatiovirhe kertoo, että palvelin- ja asiakasrenderöinti erosivat; se ei todista miksi. Sama oire voi johtua sovelluslogiikasta, selaimen muutoksesta, kirjastosta, CDN:stä, virheellisestä HTML:stä tai muuttuvasta datasta. Ei ole yhtä koodinpätkää, joka korvaisi turvallisesti kaikki nämä tapaukset.

Lisäksi hydraatiovaroitusten poistaminen ei takaa oikeellisuutta muualla. Vain-asiakas-komponentilla voi silti olla dataraceja. Deterministinen ensimmäinen renderöinti voi silti näyttää vanhentunutta dataa hydraation jälkeen. Kelvollinen DOM voi silti sisältää saavutettavuusongelmia. Käsittele hydraatiota yhtenä laatuporttina, ei ainoana.

React 19.3:n uusi browser-API ei myöskään tarkoita, että jokaisen frameworkin tulisi välittömästi korvata vakiintunut vain-selain-kuvionsa. Framework-integraatio ja asennetut versiot ovat tärkeitä. Jos projektisi on vanhemmassa React- tai Next.js-julkaisussa, seuraa kyseisen julkaisun dokumentaatiota sen sijaan, että kopioisit uudemman API:n sokeasti.

Luotettava päätöksentekojärjestys

1. Etsi pienin epäsuhtaava komponentti.
2. Tarkista muuttuvat arvot, kuten päivämäärät, satunnaisluvut, alueasetusmuotoilut ja kahdesti haettu data.
3. Poista selain-API:t ensimmäisestä palvelinyhteensopivasta renderöinnistä.
4. Varmista, että palvelin ja ensimmäinen asiakasrenderöinti käyttävät samaa datatilannekuvaa.
5. Validoi HTML-rakenne.
6. Sulje pois laajennukset, CSS-in-JS SSR -määritykset ja CDN/Edge-uudelleenkirjoitukset.
7. Käytä Effectiä, kohdennettua vain-asiakas-renderöintiä tai React 19.3:n use(browser()):ta vain, kun sisältö todella riippuu selaimesta.
8. Varaa suppressHydrationWarning pienille, tarkoituksellisille epäsuhtille.
9. Varmista uudella uudelleenlatauksella ja tuotantoversiolla.

Kestävä korjaus ei ole "saa React lopettamaan valittamisen". Se on alkuperäisen renderöintisopimuksen tekeminen eksplisiittiseksi: palvelimen ja selaimen tulisi sopia ensimmäisestä käyttöliittymästä, tai selainkohtainen osio tulisi eristää tarkoituksellisesti, jotta Reactia ei pyydetä hydraatoimaan merkintää, joka ei koskaan voisi vastata.