Miten korjata sisäinen virhe 500 Next.js Server Components -komponenteissa

Avat reitin Next.js App Router -projektissa, sivu toimi hetki sitten, ja nyt selain näyttää sisäisen palvelinvirheen tai HTTP 500 -vastauksen. Päivitys ei auta. Asiakaspuolen konsoli voi näyttää vähän hyödyllistä tietoa, koska vika tapahtui Server Component -komponentin renderöinnin aikana palvelimella.

Tilanne on niin yleinen, että se voi tuntua mysteeriltä, mutta 500-virhe ei ole diagnoosi. Se tarkoittaa, että palvelin kohtasi odottamattoman tilanteen käsitellessään pyyntöä. Next.js voi palauttaa 500-virheen käsittelemättömän sovellusvirheen vuoksi, ja Server Components -komponentit ovat erityisen tärkeitä tutkia, koska ne voivat suorittaa datan hakua, tietokantakyselyitä, todennustarkistuksia ja muuta vain palvelimella toimivaa logiikkaa renderöinnin aikana.

Versiotieto: Tarkistettu 11. syyskuuta 2026. Virallinen Next.js-dokumentaatio ilmoittaa Next.js 16.3.4:n uusimmaksi versioksi. Virheiden sanamuodot, kehityksen päällekkäiset näkymät, ajonaikainen käyttäytyminen ja käyttöönotto-lokit voivat vaihdella version ja hosting-alustan mukaan, joten käytä oman projektisi pinotaulua ensisijaisena todisteena.

Mikä yleensä aiheuttaa 500-virheen Server Component -komponentissa?

App Routerissa Next.js käyttää oletuksena Server Components -komponentteja. Virallinen Server and Client Components -dokumentaatio selittää, että Server Components -komponentit suoritetaan palvelimella ja voivat suorittaa palvelinpuolen töitä kuten datan hakua. Jos jokin näistä operaatioista heittää poikkeuksen eikä sitä käsitellä tavalla, joka tuottaa kelvollisen vastauksen tai vararatkaisun, pyyntö voi epäonnistua.

Vaihe 1: Toista epäonnistuva reitti paikallisesti ja lue palvelintuloste

Aloita helpoimmin saatavilla olevista todisteista. Suorita sama projekti paikallisesti normaalilla kehityskomennolla, kuten npm run dev, ja pyydä täsmälleen sitä reittiä, joka epäonnistuu. Älä aloita välimuistin muuttamisella, pakettien päivityksellä tai lukkotiedostojen poistamisella. Etsi ensin ensimmäinen merkityksellinen poikkeus terminaalissa, jossa Next.js on käynnissä.

Selain kertoo sinulle, että pyyntö epäonnistui; palvelimen pinotaulu kertoo todennäköisemmin miksi. Etsi ensimmäinen rivi omasta sovelluskoodistasi pikemminkin kuin viimeinen rivi frameworkin sisäosista. Kirjaa ylös reitti, tiedosto, rivinumero, virhetyyppi ja tapahtuuko vika jokaisessa pyynnössä vai vain tiettyjen tietojen kanssa.

Jos ongelma tapahtuu vain tuotannossa, käytä isäntäpalveluntarjoajasi ajonaikaisia lokeja sen sijaan. Vercelissä virallinen lokaatio-ohjeistus erottaa käännöslokit ajonaikaisista lokeista ja selittää, että ajonaikaisia merkintöjä voidaan suodattaa tilakoodin ja pyyntöpolun perusteella. Vercel dokumentoi myös, että funktion suoritusvirhe voi palauttaa 500-virheen, kun ajonaika kaatuu tai tapahtuu käsittelemätön poikkeus tai hylkäys.

Vaihe 2: Eristä datan haku ja tee virheet eksplisiittisiksi

Server Components -komponentit epäonnistuvat usein odottaessaan ylävirran API:a tai tietokantaa. Virallinen Next.js:n datan hakututoriaali näyttää Server Components -komponenttien suorittavan asynkronista palvelinpuolen datan hakua. Käsittele jokaista ulkoista riippuvuutta mahdollisena epäonnistumispisteenä.

fetch()-funktiolle erota verkkovirhe HTTP-virhevastauksesta. Vastaus, jolla on epäonnistumistila, tulisi tarkistaa ennen sen datan jäsennystä tai renderöintiä. Pieni kääre tekee todellisesta ongelmasta näkyvän palvelinlokeissa:

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

Älä lokita pääsytokeneja, evästeitä, valtuutusotsikoita, tietokantasanoja tai täydellisiä salaisia URL-osoitteita. Tilakoodi, pyyntökohteen nimi, korrelaatiotunniste ja puhdistettu virheilmoitus ovat yleensä riittäviä epäonnistuneen riippuvuuden tunnistamiseen.

Vaihe 3: Tarkista ympäristömuuttujat ja palvelin/asiakasraja

Jos sama commit toimii paikallisesti, mutta palauttaa 500-virheen käyttöönoton jälkeen, vertaa ympäristöjä ennen sovelluslogiikan muuttamista. Varmista, että jokainen vaadittu palvelinpuolen muuttuja on olemassa käyttötavoitteessa ja että arvo osoittaa palveluun, joka on saavutettavissa kyseisestä ajonaikasta. Paikallinen .env-tiedosto ei todista, että tuotantokäyttöönotossa on samat arvot.

Tutki sitten komponenttirajoja. Next.js Server Components -komponentit ovat oletus App Routerissa, kun taas interaktiivinen koodi, joka tarvitsee tilaa, efektejä, tapahtumankäsittelyä tai vain selaimessa toimivia API:a, kuuluu Client Component -komponenttiin. Virallinen Next.js-opetusmateriaali havainnollistaa komponentin siirtämistä, joka käyttää useState-hookkia, 'use client'-direktiivin taakse. Joitakin rajavirheitä havaitaan käännöksen aikana sen sijaan, että ne muuttuisivat 500-virheeksi, mutta niiden poissulkeminen estää sinua käsittelemästä koodirakenteen virhettä hosting-katkoksi.

Tarkista myös kaikki vain palvelimelle tarkoitetut paketit, jotka olettavat tietyn Node.js-ominaisuuden, tiedostojärjestelmän rakenteen, natiivin binääritiedoston tai verkkoympäristön. Riippuvuus voi toimia yhdellä koneella ja epäonnistua toisessa ajonaikassa, jos nämä oletukset eroavat.

Vaihe 4: Lisää oikea virheenkäsittely poikkeuksen piilottamisen sijaan

Kun juurisyy on tiedossa, päätä onko virhe odotettu vai odottamaton. Puuttuva tietue voi ansaita not-found-vastauksen. Validointivirhe voi ansaita normaalin viestin. Odottamaton poikkeus tulisi lokittaa ja antaa sen saavuttaa virheraja sen sijaan, että se muunnettaisiin hiljaa tyhjäksi dataksi, joka rikkoo jotain muuta.

Next.js dokumentoi erityisen error.tsx-tiedoston reittiosion virherajaksi odottamattomille virheille. Sen komponentti on Client Component ja voi tarjota uudelleenyrityksen toimitetun reset-funktion kautta. Virallinen Next.js:n virheenkäsittelyopas havainnollistaa myös notFound()-funktion käyttöä, kun pyydettyä resurssia ei ole olemassa.

'use client';

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

Virheraja parantaa käyttäjän näkemää; se ei korjaa taustalla olevaa poikkeusta. Pidä palvelinpuolen loki, joka tunnistaa syyn, äläkä paljasta herkkiä pinotauluja tai salaisia tietoja käyttöliittymässä.

Vaihe 5: Varmista korjaus tuotantomaista käännöstä vastaavassa ympäristössä

Kehityspalvelin on välttämätön diagnoosia varten, mutta se ei ole lopullinen testi. Kun reitti toimii paikallisesti, suorita tuotantokäännös projektisi paketinhallintajärjestelmällä, käynnistä se tuotantotilassa kun mahdollista ja pyydä sama reitti samoilla relevantteilla tietoehdoilla. Tarkista sitten käyttöönotettu ympäristö ajonaikaisten lokien ollessa auki.

npm run build
npm start

Jos hosting-alustasi kääntää eri tavalla kuin kannettavasi tietokoneesi, testaa myös esikatselukäyttöönotto ennen muutoksen edistämistä. Korjaus on uskottava vain, kun reitti palauttaa odotetun tilan, renderöi odotetun sisällön eikä uutta palvelinpoikkeusta ilmesty kyseiselle pyynnölle.

Miten varmistaa, että 500-virhe on todella korjattu

• Aiemmin epäonnistunut URL-osoite latautuu toistuvasti ilman HTTP 500 -vastausta.
• Palvelinterminaali tai tuotannon ajonaikaiset lokit eivät enää näytä alkuperäistä poikkeusta.
• Sama korjaus selviää npm run build:sta ja tuotantotilan suoritus tai esikatselukäyttöönotto.
• Vaaditut ympäristömuuttujat ovat läsnä ympäristössä, jossa vika alun perin tapahtui.
• Ulkoiset API- tai tietokantavirheet tuottavat nyt hallitun virhepolun selittämättömän kaatumisen sijaan.
• Interaktiivinen vain selaimessa toimiva koodi on Client Components -komponenteissa, kun taas salaiset tiedot ja etuoikeutettu datan haku pysyvät palvelimella.
• error.tsx-raja antaa käyttäjille kohtuullisen vararatkaisun odottamattomille reittiosion virheille.

Jos se epäonnistuu edelleen

Supista reittiä, kunnes se lakkaa epäonnistumasta. Korvaa väliaikaisesti yksi riippuvuus kerrallaan tunnetusti turvallisella arvolla: ensin tietokantakutsu, sitten ulkoinen API, sitten todennus tai istunnon haku, sitten alikomponentit. Ensimmäinen poistettu operaatio, joka saa 500-virheen katoamaan, tunnistaa tutkittavan alueen. Palauta jokainen riippuvuus testauksen jälkeen sen sijaan, että jätät vääriä tietoja lopulliseen sovellukseen.

Tuotantokohtaisen ongelman tapauksessa vertaa tarkkaa käyttöönotettua commitia, Node/ajonaikakonfiguraatiota, ympäristömuuttujia, verkkosaatavuutta ja riippuvuusversioita. Jos alusta ilmoittaa palveluntarjoajakohtaisen virhekoodin, käytä palveluntarjoajan virallista dokumentaatiota täsmälleen kyseiselle koodille sen sijaan, että olettaisit jokaisen 500-virheen johtuvan samasta syystä.

Tärkein vianmäärityssääntö on yksinkertainen: käsittele "Internal Error 500" oireena. Hyödyllinen todiste on palvelinpuolen poikkeus, joka tapahtui välittömästi sitä ennen. Etsi se poikkeus ensin, tee epäonnistuneesta riippuvuudesta eksplisiittinen, korjaa ympäristö tai koodiraja, joka laukaisi sen, ja varmista tulos samassa ajonaikassa, jossa ongelma tapahtui.