Kaip ištaisyti klaidą „Hydration failed because the initial UI does not match“

Rezultatas, kurio siekiate, yra paprastai aprašomas: serveryje sugeneruotas HTML turi sutapti su tuo, ką React sugeneruoja pirmojo atvaizdavimo naršyklėje metu. Kai tai yra tiesa, React gali prijungti įvykių apdorojimo funkcijas ir padaryti puslapį interaktyvų, nekeldamas hidratacijos neatitikimo klaidos, nepakeisdamas medžio dalies ir nerodydamas netikėto vizualaus šuolio.

Hidratacija yra procesas, kurio metu React perima HTML, jau atvaizduotą serveryje, ir prijungia React elgseną naršyklėje. Dabartinė React hydrateRoot dokumentacija teigia, kad kliento atvaizduotas turinys turi būti identiškas serverio atvaizduotam turiniui, o neatitikimai turėtų būti laikomi klaidomis.

Tiksli klaidos formuluotė keitėsi įvairiuose React ir karkasų (framework) leidimuose. Galite matyti senesnį pranešimą, pvz., „Hydration failed because the initial UI does not match what was rendered on the server“, arba naujesnį pranešimą, aiškinantį, kad serverio atvaizduotas medis nesutapo su kliento medžiu. Derinimo principas išlieka tas pats.

Versijos kontekstas yra svarbus. 2026 m. rugsėjo 11 d. duomenimis, oficialioje React svetainėje kaip naujausia React versija nurodyta React 19.3, o dabartinė Next.js dokumentacija kaip naujausią Next.js leidimą identifikuoja Next.js 16.3.4. Jei šį tekstą skaitote vėliau, patikrinkite React versijų puslapį ir dabartinę Next.js dokumentaciją, nes prieinamos API ir klaidų pranešimai gali keistis.

Kas laikoma sėkmingu pataisymu?

Nespręskite apie sėkmę tik pagal tai, ar dingo raudonas kūrimo aplinkos perdangos langas. Geras pataisymas turėtų atitikti kelis kriterijus:

• Hidratacijos įspėjimas arba klaida nebeatsiranda atnaujinus puslapį iš naujo.
• Pirminis serveryje atvaizduotas UI ir pirmasis naršyklės React atvaizdavimas atitinka tą patį turinį ir struktūrą.
• Paveiktas komponentas lieka interaktyvus po hidratacijos.
• Nėra akivaizdaus mirgėjimo nuo vienos reikšmės prie kitos, nebent toks pokytis yra sąmoningas ir suprojektuotas.
• Problema išlieka išspręsta gamybos (production) kompiliacijoje, o ne tik kūrimo (development) serveryje.
• Ištaisėte priežastį, o ne paslėpėte tikrąjį neatitikimą naudodami įspėjimų slopinimo parinktį.

Jei įspėjimas dingo, bet puslapis dabar atvaizduoja svarbų turinį tik įkėlus JavaScript, klaida gali būti išspręsta, tačiau vartotojo patirtis pablogėjo. Tai gali būti priimtinas kompromisas naršyklei skirtam valdikliui, bet tai nėra automatiškai geriausias rezultatas pagrindiniam puslapio turiniui.

1 žingsnis: Atkartokite neatitikimą ir raskite mažiausią neveikiantį komponentą

Pradėkite nuo kietojo atnaujinimo (hard reload) kūrimo aplinkoje ir perskaitykite visą klaidą, įskaitant komponentų steką. React 19 dokumentuotoje hidratacijos klaidoje išvardytos kelios dažnos priežastys: serverio/kliento šakojimai, tokie kaip typeof window !== 'undefined', kintančios reikšmės, tokios kaip Date.now() ar Math.random(), nuo lokalės priklausomas datų formatavimas, išoriniai duomenys, kurie pasikeitė be momentinės nuotraukos (snapshot), netinkama HTML įdėtis ir naršyklės plėtiniai, kurie modifikuoja DOM. Žr. React klaida 418.

Next.js pateikia panašų sąrašą savo oficialiame hidratacijos klaidų vadove, pridėdamas tik naršyklei skirtas API, tokias kaip window ir localStorage, CSS-in-JS konfigūraciją ir HTML, modifikuotą Edge/CDN sluoksnio.

Praktinis izoliavimo metodas – laikinai pakeisti įtartinus dinaminius skyrius deterministiniu tekstu. Jei klaida dingsta, grąžinkite tuos skyrius po vieną. Tai dažniausiai yra greičiau nei keisti globalius atvaizdavimo nustatymus, kol nežinote, kuris komponentas yra atsakingas.

Kokybės rodiklis

Esate pasirengęs judėti toliau, kai galite įvardinti tiek neveikiantį komponentą, tiek skirtingą reikšmę ar struktūrą. „Tai įvyksta kažkur valdymo skyde“ vis dar yra per plati frazė. „StatusCard laiko žyma yra generuojama nepriklausomai serveryje ir kliente“ yra veiksminga informacija.

2 žingsnis: Pašalinkite nedeterministines reikšmes iš pradinio atvaizdavimo

Deterministinis atvaizdavimas reiškia, kad tie patys įvesties duomenys sugeneruoja tą patį pradinį UI. Reikšmės, kurios nepriklausomai keičiasi tarp serverio atvaizdavimo ir naršyklės atvaizdavimo, yra dažni neatitikimų šaltiniai.

Panagrinėkite šią problematišką šabloną:

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

Serveris ir naršyklė gali vykdyti šį kodą skirtingais momentais ir skirtingose lokalėse ar laiko juostose. Geresnis sprendimas priklauso nuo to, ką puslapis turi perteikti.

Jei laiko žyma atitinka serverio duomenis, apskaičiuokite arba gaukite ją vieną kartą serveryje ir perduokite tą pačią serijalizaciją reikšmę klientui:

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

Jei reikšmė iš tikrųjų priklauso nuo vartotojo naršyklės, pirmiausia atvaizduokite stabilų vietą rezervuojantį elementą (placeholder) ir atnaujinkite jį po hidratacijos.

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

Tai veikia, nes serveris ir pirmasis kliento atvaizdavimas abu sugeneruoja tą patį vietą rezervuojantį elementą. React useEffect dokumentacija aprašo šį dviejų etapų šabloną retais atvejais, kai kliento turinys turi skirtis nuo serverio turinio.

Kada keisti metodą

Jei naršyklei skirta reikšmė yra visa komponento paskirtis – pvz., redaktorius, atkurtas iš localStorage, arba valdiklis, kuris negali prasmingai atvaizduoti turinio serveryje – priverstinis vietos rezervavimo ir efekto šablonas visame komponente gali pridėti nereikalingo sudėtingumo. Tokiu atveju vietoj to, kad apsimestumėte, jog komponentas gali būti atvaizduojamas serveryje, naudokite sąmoningą tik naršyklei skirtą ribą.

3 žingsnis: Neskaitykite tik naršyklei skirtų API pirmojo serveriui suderinamo atvaizdavimo metu

Dažnas klaidingas įsitikinimas Next.js aplinkoje yra tai, kad pridėjus 'use client', garantuojama, jog komponentas bus atvaizduojamas tik naršyklėje. Taip nėra. Next.js aiškina, kad Client Components yra riba būsenai, efektams, įvykių apdorojimo funkcijoms ir naršyklės API, tačiau Client Components vis tiek gali dalyvauti išankstiniame atvaizdavime (prerendering). Žr. dabartinę use client dokumentaciją.

Šis šablonas yra rizikingas atvaizdavimo metu:

'use client';

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

Serveryje localStorage neegzistuoja. Net ir šakojimas, toks kaip typeof window !== 'undefined', gali sugeneruoti skirtingą žymėjimą (markup) pirmojo naršyklės atvaizdavimo metu, ką tiek React, tiek Next.js dokumentuoja kaip hidratacijos neatitikimo priežastį.

Mažiems skirtumams perkelti naršyklės skaitymą į Effect. Komponentui, kuris Next.js aplinkoje turėtų būti iš tikrųjų tik naršyklei skirtas, galite dinamiškai įkelti jį išjungdami SSR:

'use client';

import dynamic from 'next/dynamic';

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

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

Next.js dokumentuoja ssr: false Client Components savo tingaus įkėlimo (lazy loading) vadove. Tas pats vadovas teigia, kad ssr: false nepalaikomas, kai bandote naudoti tą parinktį tiesiogiai Server Component; perkelti dinaminį importą į Client Component.

React 19.3: pirmos klasės tik naršyklei skirta parinktis

React 19.3 pristatė browser API. Komponentas gali iškviesti use(browser()) Suspense riboje, kad šis komponentas būtų išimtas iš serverio atvaizdavimo. Serveris atvaizduoja Suspense fallback, o komponentas normaliai atvaizduojamas naršyklėje. Žr. React browser API nuorodą.

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 programoje React teigia, kad use(browser()) turi būti kviečiamas iš Client Component. Taip pat patikrinkite, ar jūsų karkasas ir įdiegta React versija palaiko šią API, prieš ją diegdami.

4 žingsnis: Padarykite serverio duomenis ir pirmuosius kliento duomenis ta pačia momentine nuotrauka

Momentinė nuotrauka (snapshot) yra tiksli duomenų būsena, naudota sugeneruoti pradinį HTML. Hidratacija tampa trapia, jei serveris atvaizduoja vieną duomenų versiją, o klientas prieš hidratacijai pasibaigiant nedelsiant perskaito naujesnę arba kitaip surikiuotą versiją.

Pavyzdžiui, tarkime, kad serveris atvaizduoja 99 USD kainą, bet klientas nedelsiant gauna tą pačią prekę ir gauna 109 USD prieš savo pirmąjį atvaizdavimą. Problema nėra ta, kad duomenys pasikeitė; duomenų keitimas yra normalus. Problema yra ta, kad dvi aplinkos naudojo skirtingus pradinius įvesties duomenis.

Stiprus šablonas yra:

1. Gaukite pradinius duomenis serveryje.
2. Atvaizduokite HTML iš tų duomenų.
3. Perduokite arba serijalizujte tuos pačius pradinius duomenis į kliento komponentą.
4. Po hidratacijos leiskite klientui patikrinti galiojimą ir atnaujinti, jei yra naujesnių duomenų.

Teisingas įgyvendinimas priklauso nuo jūsų karkaso duomenų gavimo modelio, tačiau kokybės kriterijus lieka tas pats: serverio HTML ir pirmasis kliento medis turėtų būti pagrįsti ta pačia loginė būsena.

Kada keisti metodą

Jei turinys yra iš esmės realiu laiku ir pasenusi serverio momentinė nuotrauka klaidintų vartotojus – pvz., tiesioginės prekybos valdiklis arba greitai besikeičianti operacijų konsolė – apsvarstykite galimybę serveryje atvaizduoti stabilų apvalkalą (shell) ir įkelti tiesioginę sekciją kliente. Tai atsisako kai kurio serverio atvaizduoto turinio tam regionui, tačiau tai gali būti sąžiningiau nei hidratacija prieš duomenis, kurie garantuotai pasikeis.

5 žingsnis: Ištaisykite netinkamą HTML prieš kaltindami React

Naršyklėms leidžiama taisyti netinkamai suformuotą arba netinkamai įdėtą HTML. Tas taisymas gali sugeneruoti DOM struktūrą, kuri skiriasi nuo struktūros, kurios tikisi React, net kai JSX atrodė vizualiai tikėtinas.

Next.js aiškiai išvardija pavyzdžius, tokius kaip <div> viduje <p>, sąrašas paragrafo viduje, įdėtos nuorodos (<a>) ir įdėti mygtukai (<button>), kaip hidratacijos problemų priežastis.

Pavyzdžiui, venkite:

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

Vietoj to naudokite tinkamą struktūrą:

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

Jei komponentų biblioteka generuoja žymėjimą, tikrinkite galutinį DOM, o ne manykite, kad apvalkalų elementai yra tinkami. Lint taisyklė arba HTML validatorius gali padėti, tačiau tikrasis naršyklės DOM yra tai, ką React hidratuoja.

6 žingsnis: Atmeskite kodą už komponento ribų

Jei jūsų atvaizdavimo logika yra deterministinė ir jūsų HTML yra tinkamas, patikrinkite, ar kažkas modifikuoja serverio HTML prieš React jį hidratuojant.

Oficiali Next.js dokumentacija įvardija kelias galimybes:

• Naršyklės plėtinys pakeičia puslapį prieš React įkeliant.
• CSS-in-JS biblioteka yra neteisingai sukonfigūruota serverio atvaizdavimui.
• Edge arba CDN funkcija perrašo arba sumažina (minifies) HTML atsakymą.
• iOS aplinkoje automatinis telefono numerių, el. pašto adresų, datų ar adresų aptikimas tam tikrais atvejais gali paversti tekstą nuorodomis.

Naudokite kontroliuojamus palyginimus. Testuokite privačiame naršyklės lange su išjungtais plėtiniais. Jei klaida kyla tik už CDN, palyginkite su šaltinio (origin) atsakymu. Jei tai prasidėjo po stiliaus bibliotekos diegimo, laikykitės tos bibliotekos oficialios SSR konfigūracijos, o ne taikykite bendrą hidratacijos apėjimo būdą.

Kokybės rodiklis

Esate izoliavę šią problemų klasę, kai tas pats programos kompiliatas hidratuojasi teisingai vienoje kontroliuojamoje aplinkoje, tačiau nepavyksta po to, kai konkretus naršyklės plėtinys, proxy, CDN transformacija arba integracija pakeičia HTML.

7 žingsnis: Naudokite suppressHydrationWarning tik tikrai neišvengiamam vietiniam skirtumui

React pateikia suppressHydrationWarning={true} retais atvejais, kai vieno elemento tekstas arba atributai negali protingai sutapti, pvz., tam tikroms laiko žymoms.

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

Tai nėra bendras taisymo mechanizmas. React bendrų DOM props dokumentacija teigia, kad ši parinktį veikia tik vienu lygiu giliau ir yra skirta kaip išėjimo anga (escape hatch). Next.js hidratacijos vadovas taip pat įspėja, kad React nebandys sutvarkyti neatitinkančio teksto turinio, kai ši parinktį yra naudojama.

Naudokite ją tik tada, kai visi šie teiginiai yra teisingi:

• Skirtumas yra laukiamas ir lokalizuotas.
• Neatitikimas neatitinka neteisingos programos būsenos.
• Apkarpanti struktūra yra stabili.
• Sąmoningai priėmėte, kad pradinė serverio reikšmė ir naršyklės reikšmė skiriasi.

Jei pridėjus šią prop dingo dešimtys įspėjimų, tai yra priežastis tirti toliau, o ne ženklas, kad pagrindinė problema išspręsta.

8 žingsnis: Patikrinkite pataisymą kūrimo ir gamybos aplinkose

Kūrimo aplinkos elgsena gali skirtis nuo optimizuotos gamybos kompiliacijos. Kai klaida lokaliai dingo, atlikite gamybos stiliaus patikrą savo karkasui. Tipiniam Next.js projektui tai dažniausiai reiškia programos kompiliavimą ir paleidimą naudojant įprastas paketo valdiklio komandas, tada atliekant naujas navigacijas ir atnaujinimus.

Naudokite šį patikrinimo sąrašą:

Jei tiesiogiai valdote React SSR įėjimo tašką vietoj karkaso naudojimo, hydrateRoot taip pat palaiko klaidų grąžinimo skambučius, tokius kaip onRecoverableError, kurie gali padėti gamybos žurnalizavimui. Karkaso vartotojai paprastai neturėtų keisti karkaso hidratacijos įėjimo taško tik tam, kad pridėtų individualų apdorojimą.

Kada bandyti kitą atvaizdavimo strategiją

Kartais geriausias pataisymas nėra priversti komponentą į SSR. Apsvarstykite kitą atvaizdavimo strategiją, kai:

• Komponentas sukurtas aplink window, canvas, WebGL, naršyklės matavimus ar kitą tik naršyklei skirtą API.
• Trečiosios šalies valdiklis oficialiai nepalaiko SSR.
• Komponento prasmingas turinys visiškai priklauso nuo įrenginio vietinės būsenos, tokios kaip localStorage.
• Realaus laiko duomenys keičiasi taip greitai, kad atitikti serverio momentinę nuotrauką turi mažai vertės.

Tokiais atvejais tikslinė tik klientui skirta riba gali būti švaresnė. Raktinis žodis yra tikslinė. SSR išjungimas visam puslapiui, kad būtų pritaikyta vienam grafikui ar redaktoriui, gali be reikalo aukoti naudingą serverio atvaizduotą turinį, įkėlimo elgseną ir kitas naudas.

Dažni pataisymai, kurie atrodo sėkmingi, bet nėra

Šių pataisymų ribos

Hidratacijos klaida jums pasako, kad serverio ir kliento atvaizdavimas išsiskyrė; ji neįrodo, kodėl. Tas pats simptomas gali kilti iš programos logikos, naršyklės mutacijos, bibliotekos, CDN, netinkamo HTML arba besikeičiančių duomenų. Nėra vieno kodo fragmento, kuris saugiai išspręstų visus tuos atvejus.

Taip pat, hidratacijos įspėjimų pašalinimas negarantuoja teisingumo kitur. Tik klientui skirtas komponentas vis tiek gali turėti duomenų lenktynes. Deterministinis pirmasis atvaizdavimas vis tiek gali rodyti pasenusius duomenis po hidratacijos. Tinkamas DOM vis tiek gali turėti prieinamumo problemų. Traktuokite hidrataciją kaip vieną kokybės vartus, o ne kaip vienintelį.

React 19.3 naujas browser API taip pat nereiškia, kad kiekvienas karkasas turėtų nedelsiant pakeisti savo įsitvirtinusį tik naršyklei skirtą šabloną. Karkaso integracija ir įdiegtos versijos yra svarbios. Jei jūsų projektas naudoja senesnę React ar Next.js versiją, laikykitės tos versijos dokumentacijos, o ne aklai kopijuokite naujesnę API.

Patikima sprendimų seka

1. Raskite mažiausią komponentą, kuris nesutampa.
2. Patikrinkite besikeičiančias reikšmes, tokias kaip datos, atsitiktiniai skaičiai, lokalės formatavimas ir du kartus gauti duomenys.
3. Pašalinkite tik naršyklei skirtas API iš pirmojo serveriui suderinamo atvaizdavimo.
4. Įsitikinkite, kad serveris ir pirmasis kliento atvaizdavimas naudoja tą pačią duomenų momentinę nuotrauką.
5. Patvirtinkite HTML struktūrą.
6. Atmeskite plėtinius, CSS-in-JS SSR konfigūraciją ir CDN/Edge perrašymą.
7. Naudokite Effect, tikslinį tik kliento atvaizdavimą arba React 19.3 use(browser()) tik tada, kai turinys iš tikrųjų priklauso nuo naršyklės.
8. Rezervuokite suppressHydrationWarning mažiems, sąmoningiems neatitikimams.
9. Patikrinkite nauju atnaujinimu ir gamybos kompiliacija.

Ilgaamžis pataisymas nėra „priversti React nustoti skųstis“. Tai yra pradinio atvaizdavimo sutarties aiškinimas: serveris ir naršyklė turėtų sutarti dėl pirmojo UI, arba tik naršyklei skirta sekcija turėtų būti sąmoningai izoliuota, kad React nebūtų prašoma hidratuoti žymėjimo, kuris niekada negalėtų sutapti.