Kā novērst iekšējo kļūdu 500 Next.js Server Components

Jūs atverat maršrutu Next.js App Router projektā, pirms mirkļa lapa vēl darbojās, un tagad pārlūkā tiek rādīta iekšējā servera kļūda vai HTTP 500 atbilde. Atsvaidzināšana nepalīdz. Klienta puses konsolē var būt maz noderīgas informācijas, jo kļūme radās, kamēr Server Component tika renderēts serverī.

Šāda situācija ir tik bieža, ka var šķist noslēpumaina, taču 500 kļūda nav diagnoze. Tā nozīmē, ka serveris, apstrādājot pieprasījumu, saskārās ar negaidītu nosacījumu. Next.js var atgriezt 500 kļūdu neapstrādātas lietojumprogrammas kļūdas dēļ, un Server Components ir īpaši svarīgi pārbaudīt, jo tie renderēšanas laikā var veikt piekļuvi datiem, datubāzes vaicājumus, autentifikācijas pārbaudes un citu tikai servera loģiku.

Piezīme par versiju: pārbaudīts 2026. gada 11. septembrī, oficiālā Next.js dokumentācija norāda Next.js 16.3.4 kā jaunāko versiju. Kļūdu formulējumi, izstrādes pārklājumi, izpildes laika uzvedība un izvietošanas žurnāli var atšķirties atkarībā no versijas un hostinga platformas, tāpēc kā galveno pierādījumu izmantojiet sava projekta steka izsekošanu (stack trace).

Kas parasti izraisa 500 kļūdu Server Component?

App Router vidē Next.js pēc noklusējuma izmanto Server Components. Oficiālā Server and Client Components dokumentācija skaidro, ka Server Components izpildās serverī un var veikt servera puses darbus, piemēram, piekļuvi datiem. Ja kāda no šīm darbībām izmet izņēmumu un tas netiek apstrādāts tā, lai radītu derīgu atbildi vai rezerves risinājumu, pieprasījums var neizdoties.

1. solis: Atkārtojiet kļūstošo maršrutu lokāli un izlasiet servera izvadi

Sāciet ar vieglāk iegūstamo pierādījumu. Palaidiet to pašu projektu lokāli ar parasto izstrādes komandu, piemēram, npm run dev, un pieprasiet tieši to maršrutu, kas neizdodas. Nesāciet ar kešatmiņas maiņu, pakotņu jaunināšanu vai lockfailu dzēšanu. Vispirms atrodiet pirmo nozīmīgo izņēmumu terminālī, kur darbojas Next.js.

Pārlūks jums pasaka, ka pieprasījums neizdevās; servera steka izsekošana drīzāk pateiks, kāpēc. Meklējiet pirmo rindu savā lietojumprogrammas kodā, nevis pēdējo rindu ietvara (framework) iekšienē. Pierakstiet maršrutu, failu, rindas numuru, kļūdas tipu un to, vai kļūme rodas katrā pieprasījumā, vai tikai ar konkrētiem datiem.

Ja problēma rodas tikai produkcijas vidē, izmantojiet sava hostinga nodrošinātāja izpildes laika žurnālus. Vercel oficiālā žurnalēšanas vadlīnija atšķir būvēšanas žurnālus no izpildes laika žurnāliem un skaidro, ka izpildes laika ierakstus var filtrēt pēc statusa koda un pieprasījuma ceļa. Vercel arī dokumentē, ka funkcijas izsaukšanas kļūme var atgriezt 500 kļūdu, ja izpildes laiks avarē vai rodas neuztverts izņēmums vai noraidījums (rejection).

2. solis: Izolējiet datu ielādi un padariet kļūmes skaidras

Server Components bieži neizdodas, gaidot augšējā līmeņa API vai datubāzi. Oficiālā Next.js datu ielādes apmācība parāda, kā Server Components veic asinhronu servera puses datu piekļuvi. Uzskatiet katru ārējo atkarību par iespējamu kļūmes punktu.

Funkcijai fetch() atšķiriet tīkla kļūmi no HTTP kļūdas atbildes. Atbildei ar nesekmīgu statusu ir jāpārbauda pirms tās datu parsēšanas vai renderēšanas. Neliels apvalks padara īsto problēmu redzamu servera žurnālos:

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

  if (!apiUrl) {
    throw new Error('API_URL nav konfigurēts');
  }

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

  if (!response.ok) {
    throw new Error(`Augšējā līmeņa pieprasījums neizdevās: ${response.status}`);
  }

  return response.json();
}

Nepierakstiet piekļuves marķierus, sīkdatnes, autorizācijas galvenes, datubāzes paroles vai pilnas URL adreses ar noslēpumiem. Parasti pietiek ar statusa kodu, pieprasījuma mērķa nosaukumu, korelācijas ID un sanitizētu kļūdas ziņojumu, lai identificētu kļūstošo atkarību.

3. solis: Pārbaudiet vides mainīgos un servera/klienta robežu

Ja tas pats commits darbojas lokāli, bet pēc izvietošanas atgriež 500 kļūdu, salīdziniet vides, pirms maināt lietojumprogrammas loģiku. Pārliecinieties, ka visi nepieciešamie servera puses mainīgie eksistē izvietošanas mērķī un ka to vērtības norāda uz pakalpojumu, kas ir sasniedzams no šīs izpildes vides. Lokāls .env fails nepierāda, ka produkcijas izvietošanai ir tādas pašas vērtības.

Pēc tam pārbaudiet komponentu robežas. Next.js Server Components ir noklusējuma App Router vidē, savukārt interaktīvs kods, kam nepieciešams stāvoklis (state), efekti, notikumu apstrāde vai tikai pārlūka API, pieder pie Client Component. Oficiālais Next.js mācību materiāls demonstrē komponenta, kas izmanto useState, pārvietošanu aiz 'use client' direktīvas. Dažas robežu kļūdas tiek konstatētas kompilācijas laikā, nevis kļūst par 500 kļūdu, taču to izslēgšana novērš kodstruktūras kļūdas ārstēšanu kā hostinga traucējumu.

Pārbaudiet arī jebkuru tikai servera pakotni, kas pieņem konkrētas Node.js iespējas, failu sistēmas izkārtojumu, natīvo bināro failu vai tīkla vidi. Atkarība var darboties vienā datorā un neizdoties citā izpildes vidē, ja šie pieņēmumi atšķiras.

4. solis: Pievienojiet pareizu kļūdu apstrādi, nevis slēpiet izņēmumu

Kad pamatcēlonis ir zināms, nosakiet, vai kļūda ir sagaidāma, vai negaidīta. Trūkstošam ierakstam var būt nepieciešama atbilde "nav atrasts". Validācijas kļūmei var būt nepieciešams parasts ziņojums. Negaidīts izņēmums ir jāpieraksta žurnālā un jāļauj tam sasniegt kļūdu robežu, nevis klusi pārvērst tukšos datos, kas kaut kur citur rada problēmas.

Next.js dokumentē īpašo error.tsx failu kā maršruta segmenta kļūdu robežu negaidītām kļūdām. Tā komponents ir Client Component un var piedāvāt atkārtotu mēģinājumu, izmantojot nodrošināto reset funkciju. Oficiālā Next.js kļūdu apstrādes rokasgrāmata arī demonstrē notFound() izmantošanu, kad pieprasītais resurss neeksistē.

'use client';

export default function Error({
  reset,
}: {
  reset: () => void;
}) {
  return (
    <main>
      <h2>Kaut kas nogāja greizi.</h2>
      <button onClick={() => reset()}>Mēģiniet vēlreiz</button>
    </main>
  );
}

Kļūdu robeža uzlabo to, ko redz lietotājs; tā nelabo pamatā esošo izņēmumu. Saglabājiet servera puses žurnālu, kas identificē cēloni, un UI neeksponējiet jutīgas steka izsekošanas vai noslēpumus.

5. solis: Pārbaudiet labojumu produkcijai līdzīgā būvējumā

Izstrādes serveris ir nepieciešams diagnostikai, taču tas nav galīgais tests. Pēc tam, kad maršruts lokāli darbojas, palaidiet produkcijas būvējumu ar sava projekta pakotņu pārvaldnieku, palaidiet to produkcijas režīmā, kad tas ir praktiski iespējams, un pieprasiet to pašu maršrutu ar tām pašām attiecīgajām datu nosacījumiem. Pēc tam pārbaudiet izvietoto vidi ar atvērtiem izpildes laika žurnāliem.

npm run build
npm start

Ja jūsu hostinga platforma veido būvējumus atšķirīgi no jūsu klēpjdatora, pirms izmaiņu popularizēšanas pārbaudiet arī priekšskatījuma izvietošanu. Labojums ir ticams tikai tad, ja maršruts atgriež sagaidāmo statusu, renderē sagaidāmo saturu un šim pieprasījumam neparādās jauna servera izņēmuma kļūda.

Kā pārliecināties, ka 500 kļūda ir patiešām novērsta

• Iepriekš kļūstošā URL adrese atveras atkārtoti bez HTTP 500 atbildes.
• Servera terminālī vai produkcijas izpildes laika žurnālos vairs neparādās sākotnējais izņēmums.
• Tas pats labojums iztur npm run build un produkcijas režīma palaišanu vai priekšskatījuma izvietošanu.
• Nepieciešamie vides mainīgie ir klāt vidē, kurā sākotnēji radās kļūme.
• Ārējo API vai datubāzu kļūmes tagad rada kontrolētu kļūdu ceļu, nevis neizskaidrojamu avariju.
• Interaktīvs tikai pārlūka kods atrodas Client Components, savukārt noslēpumi un privilēģēta datu piekļuve paliek serverī.
• error.tsx robeža lietotājiem sniedz saprātīgu rezerves risinājumu negaidītām maršruta segmenta kļūdām.

Ja joprojām neizdodas

Sašauriniet maršrutu, līdz tas pārstāj kļūdīties. Pagaidām aizstājiet vienu atkarību pēc otras ar zināmu drošu vērtību: vispirms datubāzes izsaukumu, tad ārējo API, tad autentifikāciju vai sesijas meklēšanu, tad bērna komponentus. Pirmā noņemtā darbība, kas liek 500 kļūdai pazust, identificē izpētāmo apgabalu. Pēc testēšanas atjaunojiet katru atkarību, nevis atstājiet viltus datus galīgajā lietojumprogrammā.

Problēmām, kas rodas tikai produkcijā, salīdziniet precīzo izvietoto commit, Node/izpildes laika konfigurāciju, vides mainīgos, tīkla sasniedzamību un atkarību versijas. Ja platforma ziņo par pakalpojuma sniedzējam specifisku kļūdas kodu, izmantojiet pakalpojuma sniedzēja oficiālo dokumentāciju šim precīzajam kodam, nevis pieņemiet, ka visām 500 kļūdām ir vienāds cēlonis.

Galvenais problēmu novēršanas noteikums ir vienkāršs: uzskatiet "Internal Error 500" par simptomu. Noderīgākie pierādījumi ir servera puses izņēmums, kas notika tieši pirms tā. Vispirms atrodiet šo izņēmumu, padariet kļūstošo atkarību skaidru, labojiet vidi vai koda robežu, kas to izraisīja, un pārbaudiet rezultātu tajā pašā izpildes vidē, kurā radās problēma.