Hogyan javítsd meg a 500-as belső hibát a Next.js Server Components esetén

Megnyitsz egy útvonalat egy Next.js App Router projektben, az oldal pillanatokkal ezelőtt még működött, most pedig a böngésző egy Belső Szerverhibát vagy HTTP 500 választ jelenít meg. A frissítés nem segít. Az ügyféloldali konzol alig tartalmaz hasznos információt, mert a hiba a szerveren történt, miközben egy Server Component renderelődött.

Ez a helyzet elég gyakori ahhoz, hogy titokzatosnak tűnjön, de a 500-as hiba nem diagnózis. Azt jelenti, hogy a szerver egy váratlan állapottal szembesült a kérés feldolgozása közben. A Next.js akkor adhat vissza 500-as hibát, ha egy nem kezelt alkalmazáshiba történik, és a Server Components vizsgálata különösen fontos, mert ezek futtathatnak adat-hozzáférést, adatbázis-lekérdezéseket, hitelesítési ellenőrzéseket és egyéb csak szerveroldali logikát a renderelés során.

Verzió megjegyzés: 2026. szeptember 11-i ellenőrzéskor a hivatalos Next.js dokumentáció a Next.js 16.3.4 verziót jelöli meg legfrissebbként. A hibaüzenetek szövegezése, a fejlesztői overlayek, a futásidejű viselkedés és a telepítési naplók eltérhetnek a verzió és a hosting platform függvényében, ezért a saját projekted stack trace-jét használd elsődleges bizonyítékként.

Mi okoz általában 500-as hibát egy Server Componentben?

Az App Routerben a Next.js alapértelmezés szerint Server Components-t használ. A hivatalos Server and Client Components dokumentáció elmagyarázza, hogy a Server Components a szerveren futnak, és végezhetnek szerveroldali munkát, például adat-hozzáférést. Ha ezek közül az egyik művelet kivételt dob, és a kivételt nem úgy kezelik, hogy érvényes választ vagy fallbackot eredményezzen, a kérés sikertelen lehet.

1. lépés: Reprodukáld a hibás útvonalat helyileg, és olvasd el a szerver kimenetét

Kezdd a legkönnyebben beszerezhető bizonyítékkal. Futtasd ugyanazt a projektet helyileg a szokásos fejlesztési paranccsal, például npm run dev, és kérj le pontosan azt az útvonalat, amelyik hibásan viselkedik. Ne kezdj a cache beállításainak módosításával, csomagok frissítésével vagy lockfile-ok törlésével. Először keresd meg az első jelentős kivételt abban a terminálban, ahol a Next.js fut.

A böngésző azt mondja, hogy egy kérés sikertelen volt; a szerver stack trace valószínűbb, hogy megmondja, miért. Keress egy sort a saját alkalmazásod kódjában, ne a keretrendszer belsőjeiben lévő utolsó sort. Jegyezd fel az útvonalat, fájlt, sorszámot, hibatípust, és azt, hogy a hiba minden kérésnél előfordul-e, vagy csak specifikus adatok esetén.

Ha a probléma csak produkcióban fordul elő, használd a hosting szolgáltató futásidejű naplóit. A Vercel-en a hivatalos naplózási útmutató megkülönbözteti a build naplókat a futásidejű naplóktól, és elmagyarázza, hogy a futásidejű bejegyzések szűrhetők státuszkód és kérés útvonal szerint. A Vercel azt is dokumentálja, hogy egy függvényhívási hiba 500-as választ adhat, ha a runtime összeomlik, vagy egy nem kezelt kivétel vagy elutasítás történik.

2. lépés: Izold el az adatlekérést, és tedd egyértelművé a hibákat

A Server Components gyakran akkor hibásodik meg, amikor egy feljebb lévő API-ra vagy adatbázisra vár. A hivatalos Next.js adatlekérési oktatóanyag azt mutatja be, hogy a Server Components aszinkron szerveroldali adat-hozzáférést végeznek. Kezelj minden külső függőséget lehetséges hibaforrásként.

A fetch() esetén különböztesd meg a hálózati hibát a HTTP hiba választól. Egy nem sikeres státuszkódú választ ellenőrizni kell az adatok feldolgozása vagy renderelése előtt. Egy kis wrapper láthatóvá teszi a valódi problémát a szerver naplókban:

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 naplózz hozzáférési tokeneket, sütiket, authorization fejléceket, adatbázis jelszavakat vagy teljes titkokat tartalmazó URL-eket. Egy státuszkód, kérés célneve, korrelációs ID és egy szanitized hibaüzenet általában elég a hibás függőség azonosításához.

3. lépés: Ellenőrizd a környezeti változókat és a szerver/ügyfél határt

Ha ugyanaz a commit helyileg működik, de telepítés után 500-as hibát ad, hasonlítsd össze a környezeteket az alkalmazás logikájának módosítása előtt. Győződj meg róla, hogy minden szükséges szerveroldali változó létezik a telepítési célban, és hogy az érték egy olyan szolgáltatásra mutat, amely elérhető ebből a runtime-ból. Egy helyi .env fájl nem bizonyítja, hogy a produkciós telepítésnek ugyanazok az értékei vannak.

Ezután vizsgáld meg a komponens határokat. A Next.js Server Components az alapértelmezett az App Routerben, míg az interaktív kód, amely állapotot, effekteket, eseménykezelést vagy csak böngészőoldali API-kat igényel, egy Client Componentbe tartozik. A hivatalos Next.js oktatóanyag azt demonstrálja, hogyan kell egy useState-t használó komponenst egy 'use client' direktíva mögé helyezni. Néhány határ hiba a fordítás során észlelhető, és nem válik 500-as hibává, de ezek kizárása megakadályozza, hogy egy kódstruktúra hibát hosting kimaradásként kezelj.

Ellenőrizd továbbá bármely csak szerveroldali csomagot, amely egy specifikus Node.js képességre, fájlrendszer elrendezésre, natív binárisra vagy hálózati környezetre feltételezéseket támaszt. Egy függőség működhet egy gépen, de sikertelen lehet egy másik runtime-ban, ha ezek a feltételezések eltérnek.

4. lépés: Adj hozzá megfelelő hibakezelést a kivétel elrejtése helyett

Ha az alapok okozó ismert, döntsd el, hogy a hiba várt vagy váratlan. Egy hiányzó rekord egy not-found választ érdemelhet. Egy validációs hiba egy normál üzenetet érdemelhet. Egy váratlan kivételt naplózni kell, és hagyni kell, hogy elérjen egy hiba határt, ahelyett, hogy csendben üres adattá alakítanád, ami máshol okoz problémát.

A Next.js dokumentálja a speciális error.tsx fájlt mint útvonal-szegmens hiba határt váratlan hibákhoz. Ennek a komponense egy Client Component, és kínálhat újrapróbálkozást a megadott reset függvényen keresztül. A hivatalos Next.js hibakezelési útmutató azt is demonstrálja, hogyan kell a notFound() függvényt használni, amikor egy kért erőforrás nem létezik.

'use client';

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

Egy hiba határ javítja azt, amit a felhasználó lát; nem javítja meg az alapul szolgáló kivételt. Tartsd meg a szerveroldali naplót, amely azonosítja az okot, és ne fedj fel érzékeny stack trace-eket vagy titkokat a felhasználói felületen.

5. lépés: Ellenőrizd a javítást egy produkcióhoz hasonló buildben

Egy fejlesztői szerver szükséges a diagnosztikához, de nem ez a végső teszt. Miután az útvonal helyileg működik, futtass egy produkciós buildet a projekted csomagkezelőjével, indítsd el produkciós módban, ha lehetséges, és kérj le ugyanazt az útvonalat ugyanazokkal a releváns adatfeltételekkel. Ezután ellenőrizd a telepített környezetet nyitva tartott futásidejű naplókkal.

npm run build
npm start

Ha a hosting platformod másképp épít, mint a laptopod, tesztelj egy előnézeti telepítést is a változás előléptetése előtt. Egy javítás csak akkor hiteles, ha az útvonal a várt státuszt adja vissza, a várt tartalmat rendereli, és nem jelenik meg új szerverkivétel erre a kérésre.

Hogyan erősítsd meg, hogy a 500-as hiba valóban meg van javítva

• A korábban hibás URL ismételten betöltődik HTTP 500 válasz nélkül.
• A szerver terminál vagy a produkciós futásidejű naplók többé nem mutatják az eredeti kivételt.
• Ugyanaz a javítás túlél egy npm run build futtatást és egy produkciós módú futtatást vagy előnézeti telepítést.
• A szükséges környezeti változók jelen vannak abban a környezetben, ahol a hiba eredetileg előfordult.
• A külső API vagy adatbázis hibák most egy kontrollált hibaútvonalat eredményeznek egy megmagyarázhatatlan összeomlás helyett.
• Az interaktív, csak böngészőoldali kód Client Components-ben van, míg a titkok és a privilegizált adat-hozzáférés a szerveren marad.
• Egy error.tsx határ ésszerű fallbackot biztosít a felhasználóknak a váratlan útvonal-szegmens hibák esetén.

Ha továbbra is sikertelen

Csökkentsd az útvonalat, amíg meg nem szűnik a hiba. Ideiglenesen cseréld le egyenként a függőségeket egy ismert biztonságos értékkel: először az adatbázis hívást, majd a külső API-t, majd a hitelesítést vagy munkamenet-keresést, végül a gyermekkomponenseket. Az első eltávolított művelet, amely megszünteti a 500-as hibát, azonosítja a vizsgálandó területet. Állítsd vissza minden függőséget a tesztelés után, ahelyett, hogy hamis adatokat hagynál a végső alkalmazásban.

Egy csak produkcióban jelentkező probléma esetén hasonlítsd össze a pontosan telepített commitot, a Node/runtime konfigurációt, a környezeti változókat, a hálózati elérhetőséget és a függőség verziókat. Ha a platform egy szolgáltató-specifikus hibakódot jelent, használd a szolgáltató hivatalos dokumentációját pontosan ehhez a kódhoz, ahelyett, hogy feltételeznéd, hogy minden 500-as hiba ugyanannak az oknak köszönhető.

A kulcsfontosságú hibaelhárítási szabály egyszerű: kezeld a „Belső Hiba 500”-at mint tünetet. A hasznos bizonyíték a szerveroldali kivétel, amely közvetlenül előtte történt. Először keresd meg ezt a kivételt, tedd egyértelművé a hibás függőséget, javítsd meg a környezetet vagy kódhatárt, amely kiváltotta, és ellenőrizd az eredményt ugyanabban a runtime-ban, ahol a probléma előfordult.