Kaip ištaisyti vidinę 500 klaidą Next.js Server Components

Atidarote maršrutą Next.js App Router projekte, puslapis prieš akimirką veikė, o dabar naršyklėje rodoma vidinė serverio klaida arba HTTP 500 atsakymas. Atnaujinimas nepadeda. Kliento pusės konsolėje gali būti mažai naudingos informacijos, nes gedimas įvyko, kai Server Component buvo atvaizduojamas serveryje.

Tokia situacija yra pakankamai dažna, kad atrodytų paslaptinga, tačiau 500 klaida nėra diagnozė. Tai reiškia, kad serveris apdorodamas užklausą susidūrė su netikėta sąlyga. Next.js gali grąžinti 500 klaidą dėl neapdorotos programos klaidos, o Server Components yra ypač svarbūs tikrinti, nes jie gali vykdyti duomenų prieigą, duomenų bazės užklausas, autentifikacijos patikras ir kitą tik serveryje veikiančią logiką atvaizdavimo metu.

Pastaba apie versiją: patikrinta 2026 m. rugsėjo 11 d., oficialioje Next.js dokumentacijoje kaip naujausia versija nurodyta Next.js 16.3.4. Klaidų formuluotės, kūrimo perdangos, vykdymo laiko elgsena ir diegimo žurnalai gali skirtis priklausomai nuo versijos ir talpinimo platformos, todėl pagrindiniu įrodymu naudokite savo projekto krūvio seką.

Kas dažniausiai sukelia 500 klaidą Server Component?

App Router kontekste Next.js pagal nutylėjimą naudoja Server Components. Oficialioje Server and Client Components dokumentacijoje paaiškinta, kad Server Components vykdomi serveryje ir gali atlikti serverio pusės darbus, pvz., duomenų prieigą. Jei viena iš šių operacijų meta išimtį, o ji nėra apdorota taip, kad būtų sugeneruotas galiojantis atsakymas arba atsarginis variantas, užklausa gali nepavykti.

1 žingsnis: Atkartokite nepavykstantį maršrutą lokaliai ir perskaitykite serverio išvestį

Pradėkite nuo lengviausiai gaunamų įrodymų. Paleiskite tą patį projektą lokaliai su įprasta kūrimo komanda, pvz., npm run dev, ir užklauskite tikslų maršrutą, kuris nepavyksta. Nepradėkite keisti talpyklos, atnaujinti paketus ar šalinti užraktų failų. Pirmiausia raskite pirmąją reikšmingą išimtį terminale, kuriame veikia Next.js.

Naršyklė praneša, kad užklausa nepavyko; serverio krūvio seka greičiausiai pasakys, kodėl. Ieškokite pirmosios eilutės savo programos kode, o ne paskutinės eilutės karkaso viduje. Užfiksuokite maršrutą, failą, eilutės numerį, klaidos tipą ir tai, ar gedimas įvyksta kiekvienos užklausos metu, ar tik su tam tikrais duomenimis.

Jei problema kyla tik gamybos aplinkoje, vietoj to naudokite savo talpintojo vykdymo laiko žurnalus. Vercel platformoje oficialios žurnalizavimo gairės skiria kūrimo žurnalus nuo vykdymo laiko žurnalų ir paaiškina, kad vykdymo laiko įrašus galima filtruoti pagal būsenos kodą ir užklausos kelią. Vercel taip pat dokumentuoja, kad funkcijos kvietimo nesėkmė gali grąžinti 500 klaidą, kai vykdymo laikas sugriūva arba įvyksta neapdorota išimtis ar atmestas įsipareigojimas.

2 žingsnis: Izoliuokite duomenų gavimą ir padarykite gedimus aiškius

Server Components dažnai nepavyksta laukiant aukštesnio lygio API arba duomenų bazės. Oficiali Next.js duomenų gavimo pamoka parodo, kaip Server Components atlieka asinchroninę serverio pusės duomenų prieigą. Laikykite kiekvieną išorinę priklausomybę galimu gedimo tašku.

Funkcijai fetch() atskirkite tinklo gedimą nuo HTTP klaidos atsakymo. Atsakymą su nesėkmės būsenos kodu reikia patikrinti prieš analizuojant ar atvaizduojant jo duomenis. Mažas apvalkalas padaro tikrąją problemą matomą serverio žurnaluose:

async function getData() {
  const apiUrl = process.env.API_URL;

  if (!apiUrl) {
    throw new Error('API_URL is not configured');
  }

  const response = await fetch(apiUrl, { cache: 'no-store' });

  if (!response.ok) {
    throw new Error(`Upstream request failed: ${response.status}`);
  }

  return response.json();
}

Neregistruokite prieigos žetonų, slapukų, autorizacijos antraščių, duomenų bazės slaptažodžių ar pilnų slaptažodžius turinčių URL. Būsenos kodas, užklausos tikslo pavadinimas, koreliacijos ID ir išvalyta klaidos žinutė paprastai yra pakankami, kad būtų identifikuota nepavykusi priklausomybė.

3 žingsnis: Patikrinkite aplinkos kintamuosius ir serverio/kliento ribą

Jei tas pats įsipareigojimas veikia lokaliai, bet grąžina 500 klaidą po diegimo, prieš keisdami programos logiką palyginkite aplinkas. Įsitikinkite, kad kiekvienas reikalingas serverio pusės kintamasis egzistuoja diegimo tikslinėje aplinkoje ir kad jo reikšmė nurodo į paslaugą, pasiekiamą iš to vykdymo laiko. Vietinis .env failas neįrodo, kad gamybos diegime yra tos pačios reikšmės.

Tada patikrinkite komponentų ribas. Next.js Server Components yra numatytieji App Router, o interaktyvus kodas, kuriam reikia būsenos, efektų, įvykių apdorojimo ar tik naršyklėje veikiančių API, turi būti Client Component. Oficialios Next.js mokymo medžiagos parodo, kaip komponentą, naudojantį useState, perkelti už 'use client' direktyvos. Kai kurios ribų klaidos yra aptinkamos kompiliavimo metu, o ne tampa 500 klaida, tačiau jų pašalinimas neleidžia klaidos kodų struktūroje laikyti talpinimo sutrikimu.

Taip pat patikrinkite bet kokį tik serveryje veikiančią paketą, kuris daro prielaidą apie konkrečias Node.js galimybes, failų sistemos išdėstymą, natyvųjį binarinį failą ar tinklo aplinką. Priklausomybė gali veikti viename kompiuteryje ir nepavykti kitoje vykdymo aplinkoje, jei šios prielaidos skiriasi.

4 žingsnis: Pridėkite tinkamą klaidų apdorojimą vietoj išimties slėpimo

Kai pagrindinė priežastis žinoma, nuspręskite, ar klaida yra tikėtina, ar netikėta. Trūkstamas įrašas gali reikalauti „nerasta“ atsakymo. Patvirtinimo nesėkmė gali reikalauti įprastos žinutės. Netikėtą išimtį reikia užregistruoti ir leisti jai pasiekti klaidų ribą, o ne tyliai paversti tuščiais duomenimis, kurie sugenda kitur.

Next.js dokumentuoja specialų error.tsx failą kaip maršruto segmento klaidų ribą netikėtoms klaidoms. Jo komponentas yra Client Component ir gali pasiūlyti pakartotinį bandymą per pateiktą reset funkciją. Oficiali Next.js klaidų apdorojimo vadovas taip pat parodo, kaip naudoti notFound(), kai prašomas resursas neegzistuoja.

'use client';

export default function Error({
  reset,
}: {
  reset: () => void;
}) {
  return (
    <main>
      <h2>Something went wrong.</h2>
      <button onClick={() => reset()}>Try again</button>
    </main>
  );
}

Klaidų riba pagerina tai, ką mato vartotojas; ji neištaiso pagrindinės išimties. Palikite serverio pusės žurnalą, kuris identifikuoja priežastį, ir neatskleiskite jautrių krūvio sekų ar slaptažodžių vartotojo sąsajoje.

5 žingsnis: Patvirtinkite pataisymą gamybai panašiame sukūrimo procese

Kūrimo serveris yra būtinas diagnostikai, tačiau tai nėra galutinis testas. Kai maršrutas veikia lokaliai, paleiskite gamybos sukūrimą naudodami savo projekto paketų tvarkyklę, jei įmanoma, paleiskite jį gamybos režimu ir užklauskite to paties maršruto su tomis pačiomis atitinkamomis duomenų sąlygomis. Tada patikrinkite diegimo aplinką atidarius vykdymo laiko žurnalus.

npm run build
npm start

Jei jūsų talpinimo platforma kuria kitaip nei jūsų nešiojamas kompiuteris, prieš skelbdami pakeitimą taip pat išbandykite peržiūros diegimą. Pataisymas yra patikimas tik tada, kai maršrutas grąžina tikėtiną būseną, atvaizduoja tikėtiną turinį ir tam užklausai neatsiranda nauja serverio išimtis.

Kaip patvirtinti, kad 500 klaida iš tikrųjų ištaisyta

• Anksčiau nepavykęs URL pakartotinai įkeliamas be HTTP 500 atsakymo.
• Serverio terminale arba gamybos vykdymo laiko žurnaluose neberodoma pradinė išimtis.
• Tas pats pataisymas išlieka po npm run build ir gamybos režimo paleidimo arba peržiūros diegimo.
• Reikalingi aplinkos kintamieji yra toje aplinkoje, kurioje gedimas įvyko iš pradžių.
• Išorinių API arba duomenų bazės gedimai dabar sukuria kontroliuojamą klaidų kelią, o ne nepaaiškinamą avariją.
• Interaktyvus, tik naršyklėje veikiantis kodas yra Client Components, o slaptažodžiai ir privilegijuota duomenų prieiga lieka serveryje.
• error.tsx riba suteikia vartotojams pagrįstą atsarginį variantą netikėtiems maršruto segmento gedimams.

Jei vis tiek nepavyksta

Supaprastinkite maršrutą, kol jis nustos strigti. Laikinai pakeiskite vieną priklausomybę po kitos žinoma saugia reikšme: pirmiausia duomenų bazės skambutį, tada išorinį API, tada autentifikaciją arba seanso paiešką, tada vaiko komponentus. Pirmoji pašalinta operacija, dėl kurios 500 klaida dingsta, nurodo sritį, kurią reikia tirti. Po testavimo atkurkite kiekvieną priklausomybę, o ne palikite netikrus duomenis galutinėje programoje.

Tik gamybos aplinkoje pasitaikančiai problemai palyginkite tikslų įdiegtą įsipareigojimą, Node/vykdymo laiko konfigūraciją, aplinkos kintamuosius, tinklo pasiekiamumą ir priklausomybių versijas. Jei platforma praneša apie tiekėjui specifinį klaidos kodą, naudokite oficialią to tiekėjo dokumentaciją būtent tam kodui, o ne darykite prielaidą, kad visos 500 klaidos turi tą pačią priežastį.

Pagrindinė trikčių šalinimo taisyklė yra paprasta: „Internal Error 500“ laikykite simptomu. Naudingi įrodymai yra serverio pusės išimtis, įvykusi iškart prieš tai. Pirmiausia raskite tą išimtį, padarykite nepavykusią priklausomybę aiškią, ištaisykite aplinką arba kodo ribą, kuri ją sukėlė, ir patvirtinkite rezultatą toje pačioje vykdymo aplinkoje, kurioje problema įvyko.