Kako odpraviti notranjo napako 500 v strežniških komponentah Next.js

Odprete pot v projektu Next.js App Router, stran je bila pred trenutkom še delovala, zdaj pa brskalnik prikaže notranjo strežniško napako ali odgovor HTTP 500. Osvežitev ne pomaga. Konzola na strani odjemalca morda ne prikazuje veliko uporabnih informacij, ker je do napake prišlo med izvajanjem strežniške komponente na strežniku.

Ta situacija je dovolj pogosta, da se zdi skrivnostna, vendar napaka 500 ni diagnoza. Pomeni, da je strežnik naletel na nepričakovano stanje med obdelavo zahteve. Next.js lahko vrne napako 500 zaradi neobravnavane aplikacijske napake, strežniške komponente pa je še posebej pomembno pregledati, ker lahko med izvajanjem izvajajo dostop do podatkov, poizvedbe v bazo, preverjanje pristnosti in drugo logiko, ki je na voljo samo na strežniku.

Opomba o različici: kot je bilo preverjeno 11. septembra 2026, uradna dokumentacija Next.js navaja Next.js 16.3.4 kot najnovejšo različico. Besedilo napak, razvojni preklopni sloji, obnašanje v času izvajanja in dnevniki uvajanja se lahko razlikujejo glede na različico in gostiteljsko platformo, zato uporabite sledi klica iz svojega projekta kot glavni dokaz.

Kaj običajno povzroči napako 500 v strežniški komponenti?

V App Routerju Next.js privzeto uporablja strežniške komponente. Uradna dokumentacija o strežniških in odjemalskih komponentah pojasnjuje, da se strežniške komponente izvajajo na strežniku in lahko opravljajo delo na strani strežnika, kot je dostop do podatkov. Če ena od teh operacij sproži izjemo in izjema ni obravnavana na način, ki ustvari veljaven odgovor ali nadomestno vsebino, lahko zahteva ne uspe.

Verjeten vzrok	Kaj iskati	Prvi korak
Neuspela zahteva API	Napake DNS, napake povezave, nepričakovani odgovori 401/403/404/500, neveljaven JSON	Zabeležite status zgornjega toka in preverite response.ok
Napaka baze podatkov	Napake povezave, manjkajoča tabela, potekla poverila, izjeme pri poizvedbah	Izvedite poizvedbo neodvisno in preglejte strežniške dnevnike
Manjkajoča spremenljivka okolja	undefined URL, žeton, niz za povezavo ali skrivnost	Ločeno preverite nastavitve lokalnega in uvajalnega okolja
Težava z mejo med strežnikom/odjemalcem	Kavelj, brskalniški API ali interaktivna koda, uporabljena v napačni komponenti	Premaknite interaktivno kodo za mejo 'use client'
Neobravnavana aplikacijska izjema	Sled klica kaže na vašo stran, postavitev, pomožno funkcijo, kodo za preverjanje pristnosti ali knjižnico	Popravite vrstico, ki sproži napako, nato dodajte ustrezno mejo napake
Težava z uvajanjem/časom izvajanja	Deluje lokalno, a odpove šele po uvajanju	Primerjajte spremenljivke časa izvajanja, mrežni dostop, predpostavke Node/časa izvajanja in produkcijske dnevnike

Korak 1: Ponovite neuspešno pot lokalno in preberite izhod strežnika

>Začnite z najlažje dostopnimi dokazi. Zaženite isti projekt lokalno s svojim običajnim razvojnim ukazom, kot je npm run dev, in zahtevajte natančno pot, ki odpove. Ne začnite s spreminjanjem predpomnjenja, nadgrajevanjem paketov ali brisanjem zaklepnih datotek. Najprej poiščite prvo smiselno izjemo v terminalu, kjer teče Next.js.

Brskalnik vam pove, da je zahteva neuspela; strežniška sled klica vam bo verjetneje povedala, zakaj. Poiščite prvo vrstico v kodi svoje aplikacije, ne zadnje vrstice znotraj notranjosti ogrodja. Zabeležite pot, datoteko, številko vrstice, vrsto napake in ali do napake pride pri vsaki zahtevi ali samo pri določenih podatkih.

Če se težava pojavi samo v produkciji, namesto tega uporabite dnevnike časa izvajanja svojega gostitelja. Na Vercelu uradni vodič za dnevnikovanje razlikuje med gradbenimi dnevniki in dnevniki časa izvajanja ter pojasnjuje, da se vnosi časa izvajanja lahko filtrirajo po statusni kodi in poti zahteve. Vercel tudi dokumentira, da neuspeh klica funkcije lahko vrne napako 500, kadar se čas izvajanja zruši ali pride do nepujene izjeme ali zavrnitve.

Korak 2: Izolirajte pridobivanje podatkov in naredite napake eksplicitne

Strežniške komponente pogosto odpovejo, medtem ko čakajo na zgornji API ali bazo podatkov. Uradni vodič Next.js za pridobivanje podatkov prikazuje strežniške komponente, ki izvajajo asinhroni dostop do podatkov na strani strežnika. Obravnavajte vsako zunanjo odvisnost kot možno točko napake.

Pri fetch() razlikujte med napako omrežja in odgovorom HTTP z napako. Odgovor z neuspešnim statusom je treba preveriti pred razčlenjevanjem ali upodabljanjem njegovih podatkov. Majhen ovojnica naredi pravi problem vidnega v strežniških dnevnikih:

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

Ne beležite dostopovnih žetonov, piškotkov, glav za preverjanje pristnosti, gesel za bazo podatkov ali celotnih URL-jev s skrivnostmi. Statusna koda, ime cilja zahteve, ID korelacije in očiščeno sporočilo o napaki so običajno dovolj za identifikacijo odpovedle odvisnosti.

Korak 3: Preverite spremenljivke okolja in mejo med strežnikom/odjemalcem

Če isti predložek deluje lokalno, a po uvajanju vrne napako 500, primerjajte okolja, preden spremenite logiko aplikacije. Potrdite, da vsaka zahtevana spremenljivka na strani strežnika obstaja v cilju uvajanja in da vrednost kaže na storitev, ki je dosegljiva iz tega časa izvajanja. Lokalna datoteka .env ne dokazuje, da ima produkcijska namestitev enake vrednosti.

Nato preglejte meje komponent. Strežniške komponente Next.js so privzete v App Routerju, medtem ko interaktivna koda, ki potrebuje stanje, učinke, obravnavo dogodkov ali API-je, ki so na voljo samo v brskalniku, spada v odjemalsko komponento. Uradno izobraževalno gradivo Next.js demonstrira premik komponente, ki uporablja useState, za direktivo 'use client'. Nekatere napake pri mejah so ujetе med prevajanjem, namesto da bi postale napaka 500, vendar njihova izključitev prepreči, da bi napako v strukturi kode obravnavali kot izpad gostovanja.

Preverite tudi kateri koli paket, ki je namenjen samo strežniku in predpostavlja določeno zmogljivost Node.js, postavitev datotečnega sistema, nativni binarni datoteki ali mrežno okolje. Odvisnost lahko deluje na enem računalniku in odpove v drugem času izvajanja, če se te predpostavke razlikujejo.

Korak 4: Dodajte pravilno obravnavo napak namesto skrivanja izjeme

Ko je koreninski vzrok znan, se odločite, ali je napaka pričakovana ali nepričakovana. Manjkajoč zapis morda zasluži odgovor "ni najdeno". Napaka pri preverjanju veljavnosti morda zasluži običajno sporočilo. Nepričakovana izjema mora biti zabeležena in dovoljeno, da doseže mejo napake, namesto da bi bila tiho pretvorjena v prazne podatke, ki pokvarijo nekaj drugega.

Next.js dokumentira posebno datoteko error.tsx kot mejo napak za segment poti za nepričakovane napake. Njena komponenta je odjemalska komponenta in lahko ponudi poskus znova prek zagotovljene funkcije reset. Uradni vodič Next.js za obravnavo napak tudi demonstrira uporabo notFound(), kadar zahtevani vir ne obstaja.

'use client';

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

Meja napake izboljša to, kar vidi uporabnik; ne popravi osnovne izjeme. Ohranite strežniški dnevnik, ki identificira vzrok, in ne izpostavljajte občutljivih sledi klica ali skrivnosti v uporabniškem vmesniku.

Korak 5: Preverite popravek v gradnji, podobni produkciji

Razvojni strežnik je potreben za diagnozo, vendar ni končni test. Ko pot deluje lokalno, zaženite produkcijsko gradnjo z upraviteljem paketov svojega projekta, jo zaženite v produkcijskem načinu, kadar je to izvedljivo, in zahtevajte isto pot z enakimi relevantnimi pogoji podatkov. Nato preverite uvajalno okolje z odprtimi dnevniki časa izvajanja.

npm run build
npm start

Če vaša gostiteljska platforma gradi drugače kot vaš prenosnik, pred promocijo spremembe preizkusite tudi uvajanje za predogled. Popravek je verodostojen le, kadar pot vrne pričakovani status, upodobi pričakovano vsebino in se za to zahtevo ne pojavi nova strežniška izjema.

Kako potrditi, da je napaka 500 dejansko odpravljena

• Prej neuspešen URL se naloži večkrat brez odgovora HTTP 500.
• Terminal strežnika ali dnevniki časa izvajanja v produkciji ne prikazujejo več prvotne izjeme.
• Isti popravek preživi npm run build in zagon v produkcijskem načinu ali uvajanje za predogled.
• Zahtevane spremenljivke okolja so prisotne v okolju, kjer je do napake prvotno prišlo.
• Napake zunanjega API-ja ali baze podatkov zdaj povzročijo nadzorovano pot napake namesto nepojasnjenega zrušitve.
• Interaktivna koda, ki je na voljo samo v brskalniku, je znotraj odjemalskih komponent, medtem ko skrivnosti in privilegiran dostop do podatkov ostanejo na strežniku.
• Meja error.tsx uporabnikom zagotovi razumen nadomestni prikaz za nepričakovane napake segmenta poti.

Če še vedno odpove

Zmanjšajte pot, dokler ne preneha odpovedovati. Začasno zamenjajte eno odvisnost za drugo z znano varno vrednostjo: najprej klic baze podatkov, nato zunanji API, nato preverjanje pristnosti ali iskanje seje, nato podrejene komponente. Prva odstranjena operacija, zaradi katere napaka 500 izgine, identificira področje za preiskavo. Po testiranju vsako odvisnost obnovite, namesto da bi v končni aplikaciji pustili lažne podatke.

Za težavo, ki se pojavi samo v produkciji, primerjajte natančno uvajalni commit, konfiguracijo Node/časa izvajanja, spremenljivke okolja, mrežno dosegljivost in različice odvisnosti. Če platforma poroča o kodi napake, specifični za ponudnika, uporabite uradno dokumentacijo ponudnika za to natančno kodo, namesto da bi predpostavljali, da ima vsaka napaka 500 isti vzrok.

Ključno pravilo za odpravljanje težav je preprosto: "Notranja napaka 500" obravnavajte kot simptom. Uporaben dokaz je strežniška izjema, ki se je zgodila tik pred njo. Najprej poiščite to izjemo, naredite odpovedlo odvisnost eksplicitno, popravite okolje ali mejo kode, ki jo je sprožila, in preverite rezultat v istem času izvajanja, kjer je prišlo do težave.