Hvernig á að laga innri villu 500 í Next.js Server Components

Þú opnar áfangastað í Next.js App Router verkefni, síðan virkaði fyrir augnabliki síðan, og nú sýnir vafrið innri serveravillu (Internal Server Error) eða HTTP 500 svar. Endurhleðsla hjálpar ekki. Vafrahliðarstýrið (console) gæti sýnt lítil gagnleg upplýsingar vegna þess að bilunin átti sér stað meðan Server Component var að teikna (render) á servernum.

Það ástand er algengt nokkuð til að virka dularfullt, en 500 er ekki greining. Það þýðir að serverinn rakst á óvænta aðstæður við meðhöndlun beiðninnar. Next.js getur skilað 500 fyrir ómeðhöndlaða forritsvillu, og Server Components eru sérstaklega mikilvægar að skoða vegna þess að þær geta keyrt aðgang að gögnum, gagnagrunnsspurningar, auðkenningarathuganir og aðra server-eina rökræði meðan á teiknun stendur.

Útgáfuathugasemd: eins og staðfest var þann 11. september 2026, listar opinbera Next.js skjölunin Next.js 16.3.4 sem nýjustu útgáfuna. Orðalag villna, þróunaroverlays, keyrsluhegðun og útfærsluloggar (deployment logs) geta verið mismunandi eftir útgáfu og hýsingarvettvangi, svo notaðu stack trace úr þínu eigin verkefni sem fyrstu sönnunargögn.

Hvað veldur yfirleitt 500 í Server Component?

Í App Router notar Next.js Server Components sjálfgefið. Opinbera Server and Client Components skjölunin útskýrir að Server Components keyra á servernum og geta framkvæmt server-hliðar vinnu eins og aðgang að gögnum. Ef ein af þessum aðgerðum kastar undantekningu (throws) og undantekningin er ekki meðhöndluð á hátt sem skilar gildu svari eða fallback, getur beiðnin mistekist.

Skref 1: Endurskapaðu mistekna áfangastaðinn staðbundið og lestu server úttakið

Byrjaðu með auðveldustu sönnunargögnin til að fá. Keyrðu sama verkefni staðbundið með venjulegu þróunarskipuninni þinni, eins og npm run dev, og beiðstu um nákvæman áfangastaðinn sem mistekst. Ekki byrja á að breyta skyndiminni (caching), uppfæra pakka eða eyða lockfiles. Finndu fyrstu marktæku undantekninguna í terminalnum þar sem Next.js keyrir.

Vafrið segir þér að beiðni hafi mistekist; server stack trace er líklegra til að segja þér hvers vegna. Leitaðu að fyrstu línunni í þínu eigin forritskóða frekar en síðustu línunni inni í framework innviðum. Skráðu áfangastaðinn, skrána, línunúmer, villutegund og hvort bilunin eigi sér stað við hverja beiðni eða aðeins með ákveðnum gögnum.

Ef vandamálið á sér aðeins stað í framleiðslu, notaðu keyrslu logga hýsingarinnar þinnar. Á Vercel, greinir opinbera logga leiðbeiningin á milli byggingarlogga og keyrslulogga og útskýrir að keyrslufærslur séu hægt að sía eftir stöðukóða og beiðnarleið. Vercel skjalsetur einnig að function invocation failure getur skilað 500 þegar keyrslan hrynur eða ófangað undantekning eða höfnun (rejection) á sér stað.

Skref 2: Einangraðu gagnainnsókn og gerðu bilanir skýrar

Server Components mistekst oftast í bið eftir upstream API eða gagnagrunni. Opinbera Next.js gagnainnsóknar kennsluefnið sýnir Server Components framkvæma ósamhæfða (asynchronous) server-hliðar aðgang að gögnum. Meðhöndlaðu hverja ytri háð sem mögulega bilunarpunkt.

Fyrir fetch(), greindu á milli netbilunar og HTTP villusvars. Svar með ósigurs stöðu ætti að athuga áður en gögnin eru pörsuð eða teiknuð. Lítil wrapper gerir raunverulega vandamálið sýnilegt í server loggum:

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

Ekki logga aðgangstokens, cookies, authorization headers, gagnagrunnslykilorð eða fullar leyndarmál-berandi URL. Stöðukóði, beiðnarmarknafn, correlation ID og hreinsað villuskilaboð eru venjulega nægjanleg til að auðkenna misteknu háðina.

Skref 3: Athugaðu umhverfisbreytur og server/client mörkin

Ef sama commit virkar staðbundið en skilar 500 eftir útfærslu, berðu saman umhverfin áður en þú breytir forritarökræðum. Staðfestu að hver nauðsynleg server-hliðar breyta sé til staðar í útfærslumarkmiðinu og að gildið vísi á þjónustu sem er náanleg frá þeirri keyrslu. Staðbundin .env skrá sannar ekki að framleiðsluútfærslan hafi sömu gildi.

Skoðaðu síðan component mörkin. Next.js Server Components eru sjálfgefið í App Router, en gagnvirkt kóði sem þarf state, effects, event handling eða vafra-eina API tilheyrir Client Component. Opinbera Next.js kennsluefnið sýnir að færa component sem notar useState aftan við 'use client' directive. Sum mörkavillur eru fangaðar við þýðingu (compilation) frekar en að verða að 500, en að útiloka þær kemur í veg fyrir að þú meðhöndlar kóðastrúkturvillu sem hýsingarbilun.

Athugaðu einnig hvaða server-eina pakka sem gerir ráð fyrir ákveðinni Node.js getu, skráakerfisuppbyggingu, native binary eða netumhverfi. Háð getur virkað á einni vél og mistekist í annarri keyrslu ef þessar forsendur eru mismunandi.

Skref 4: Bættu við réttri villumeðhöndlun í stað þess að fela undantekninguna

Þegar rót orsakarinn er þekkt, ákvarðaðu hvort villan er væntanleg eða óvænt. Vantar skrá gæti átt skilið not-funduð svar (not-found response). Staðfestingarbilun gæti átt skilið venjulegt skilaboð. Óvænt undantekning ætti að logga og leyfa að ná error boundary frekar en að vera þögult umbreytt í tómt gögn sem skemmist einhvers staðar annars staðar.

Next.js skjalsetur sérstaka error.tsx skrána sem route-segment error boundary fyrir óvæntar villur. Component hennar er Client Component og getur boðið upp á endurtilraun í gegnum veittu reset fallið. Opinbera Next.js villumeðhöndlunar leiðbeiningin sýnir einnig notkun á notFound() þegar óskað er eftir auðlind sem er ekki til.

'use client';

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

Error boundary bætir það sem notandinn sér; það lagar ekki undirliggjandi undantekninguna. Haltu server-hliðar logginu sem auðkennir orsökina, og ekki birta viðkvæma stack traces eða leyndarmál í UI.

Skref 5: Staðfestu lagfæringuna í framleiðslulíkri byggingu

Þróunarserver er nauðsynlegur fyrir greiningu, en hann er ekki lokaprófið. Eftir að áfangastaðurinn virkar staðbundið, keyrðu framleiðslubyggingu með pakka stjórnara verkefnisins þíns, keyrðu hana í framleiðsluham ef mögulegt er, og beiðstu um sama áfangastað með sömu viðeigandi gögnum. Staðfestu síðan útfærsla umhverfið með keyrslu logga opna.

npm run build
npm start

Ef hýsingarvettvangurinn þinn byggir öðruvísi en fartölvan þín, prófaðu einnig forskoðunarútfærslu (preview deployment) áður en þú kynntir breytinguna. Lagfæring er trúverðug aðeins þegar áfangastaðurinn skilar væntanlegri stöðu, teiknar væntanlegt efni, og engin ný server undantekning birtist fyrir þá beiðni.

Hvernig á að staðfesta að 500 sé í raun lagað

• Áður mistekna URL hleðst endurtekið án HTTP 500 svars.
• Server terminalinn eða framleiðslu keyrslu loggar sýna ekki lengur upprunalegu undantekninguna.
• Sama lagfæring lifir af npm run build og keyrslu í framleiðsluham eða forskoðunarútfærslu.
• Nauðsynlegar umhverfisbreytur eru til staðar í umhverfinu þar sem bilunin átti sér stað upphaflega.
• Ytri API eða gagnagrunnsbilanir framleiða núna stjórnaða villuleið í stað óútskýrðs hruns.
• Gagnvirkt vafra-eina kóði er inni í Client Components, en leyndarmál og forgangur aðgangur að gögnum halda á servernum.
• error.tsx boundary gefur notendum sanngjarna fallback fyrir óvæntar route-segment bilanir.

Ef það mistekst ennþá

Minnkaðu áfangastaðinn þar til hann hættir að mistekjast. Skiptu út einni háð í einu tímabundið við þekkt öruggt gildi: fyrst gagnagrunnsbeiðnina, síðan ytri API, síðan auðkenningu eða session leit, síðan barna components. Fyrsta fjarlægða aðgerðin sem gerir 500 hverfa auðkennir svæðið til að rannsaka. Endurheimtu hverja háð eftir prófun frekar en að skilja eftir fölsk gögn í lokaforritinu.

Fyrir framleiðslu-eina vandamál, berðu saman nákvæma útfærða commit, Node/keyrslu stillingar, umhverfisbreytur, netnáanleika og útgáfur háða. Ef vettvangurinn tilkynnir veitara-sérstakan villukóða, notaðu opinberu skjölun veitarans fyrir þann nákvæma kóða frekar en að gera ráð fyrir að hver 500 hafi sömu orsök.

Lykilreglan í villuleit er einföld: meðhöndla “Internal Error 500” sem einkennið. Gagnlegu sönnunargögnin eru server-hliðar undantekningin sem átti sér stað strax á undan henni. Finndu þá undantekningu fyrst, gerðu misteknu háðina skýra, lagaðu umhverfið eða kóðamörkin sem kallaði hana fram, og staðfestu niðurstöðuna í sömu keyrslu þar sem vandamálið átti sér stað.