Πώς να διορθώσετε το Εσωτερικό Σφάλμα 500 στα Server Components του Next.js

Ανοίγετε μια διαδρομή σε ένα έργο Next.js App Router, η σελίδα λειτουργούσε πριν από λίγο και τώρα το πρόγραμμα περιήγησης εμφανίζει ένα Εσωτερικό Σφάλμα Διακομιστή ή μια απόκριση HTTP 500. Η ανανέωση δεν βοηθά. Η κονσόλα του πελάτη μπορεί να δείχνει λίγες χρήσιμες πληροφορίες επειδή η αποτυχία συνέβη κατά την απόδοση ενός Server Component στον διακομιστή.

Αυτή η κατάσταση είναι αρκετά συνηθισμένη ώστε να φαίνεται μυστηριώδης, αλλά ένα σφάλμα 500 δεν είναι διάγνωση. Σημαίνει ότι ο διακομιστής αντιμετώπισε μια μη αναμενόμενη κατάσταση κατά την επεξεργασία του αιτήματος. Το Next.js μπορεί να επιστρέψει ένα σφάλμα 500 για ένα μη χειρισμένο σφάλμα εφαρμογής, και τα Server Components είναι ιδιαίτερα σημαντικά για επιθεώρηση επειδή μπορούν να εκτελέσουν πρόσβαση σε δεδομένα, ερωτήματα βάσης δεδομένων, ελέγχους ταυτοποίησης και άλλη λογική αποκλειστικά για τον διακομιστή κατά την απόδοση.

Σημείωση έκδοσης: όπως ελέγχθηκε στις 11 Σεπτεμβρίου 2026, η επίσημη τεκμηρίωση του Next.js αναφέρει την έκδοση Next.js 16.3.4 ως την πιο πρόσφατη. Η διατύπωση των σφαλμάτων, τα επικαλύμματα ανάπτυξης, η συμπεριφορά του χρόνου εκτέλεσης και τα αρχεία καταγραφής ανάπτυξης μπορεί να διαφέρουν ανάλογα με την έκδοση και την πλατφόρμα φιλοξενίας, οπότε χρησιμοποιήστε το stack trace από το δικό σας έργο ως κύρια απόδειξη.

Τι προκαλεί συνήθως ένα σφάλμα 500 σε ένα Server Component;

Στο App Router, το Next.js χρησιμοποιεί Server Components από προεπιλογή. Η επίσημη τεκμηρίωση για τα Server και Client Components εξηγεί ότι τα Server Components εκτελούνται στον διακομιστή και μπορούν να εκτελούν εργασίες πλευράς διακομιστή όπως η πρόσβαση σε δεδομένα. Εάν μία από αυτές τις λειτουργίες προκαλέσει εξαίρεση και η εξαίρεση δεν χειριστεί με τρόπο που παράγει μια έγκυρη απόκριση ή εναλλακτική λύση, το αίτημα μπορεί να αποτύχει.

Βήμα 1: Αναπαράγετε την αποτυχημένη διαδρομή τοπικά και διαβάστε την έξοδο του διακομιστή

Ξεκινήστε με την πιο εύκολη απόδειξη που μπορείτε να αποκτήσετε. Εκτελέστε το ίδιο έργο τοπικά με τη συνήθη εντολή ανάπτυξης, όπως npm run dev, και ζητήστε την ακριβή διαδρομή που αποτυγχάνει. Μην ξεκινήσετε αλλάζοντας την κρυφή μνήμη, αναβαθμίζοντας πακέτα ή διαγράφοντας αρχεία κλειδώματος. Πρώτα βρείτε την πρώτη ουσιαστική εξαίρεση στο τερματικό όπου εκτελείται το Next.js.

Το πρόγραμμα περιήγησης σας λέει ότι ένα αίτημα απέτυχε· το stack trace του διακομιστή είναι πιο πιθανό να σας πει γιατί. Αναζητήστε την πρώτη γραμμή στον κώδικα της εφαρμογής σας αντί για την τελευταία γραμμή στα εσωτερικά του framework. Καταγράψτε τη διαδρομή, το αρχείο, τον αριθμό γραμμής, τον τύπο σφάλματος και εάν η αποτυχία συμβαίνει σε κάθε αίτημα ή μόνο με συγκεκριμένα δεδομένα.

Εάν το πρόβλημα συμβαίνει μόνο στην παραγωγή, χρησιμοποιήστε τα αρχεία καταγραφής χρόνου εκτέλεσης του host σας. Στην Vercel, η επίσημη οδηγός καταγραφής διαχωρίζει τα αρχεία καταγραφής ανάπτυξης από τα αρχεία καταγραφής χρόνου εκτέλεσης και εξηγεί ότι οι καταχωρήσεις χρόνου εκτέλεσης μπορούν να φιλτραριστούν ανά κωδικό κατάστασης και διαδρομή αιτήματος. Η Vercel τεκμηριώνει επίσης ότι μια αποτυχία κλήσης συνάρτησης μπορεί να επιστρέψει ένα σφάλμα 500 όταν ο χρόνος εκτέλεσης καταρρέει ή συμβαίνει μια μη συλληφθείσα εξαίρεση ή απόρριψη.

Βήμα 2: Απομονώστε την ανάκτηση δεδομένων και κάντε τις αποτυχίες ρητές

Τα Server Components αποτυγχάνουν συχνά ενώ περιμένουν ένα upstream API ή βάση δεδομένων. Η επίσημη εκπαίδευση ανάκτησης δεδομένων του Next.js δείχνει τα Server Components να εκτελούν ασύγχρονη πρόσβαση σε δεδομένα πλευράς διακομιστή. Θεωρήστε κάθε εξωτερική εξάρτηση ως πιθανό σημείο αποτυχίας.

Για το fetch(), διαχωρίστε μια αποτυχία δικτύου από μια απόκριση σφάλματος HTTP. Μια απόκριση με μη επιτυχημένη κατάσταση πρέπει να ελέγχεται πριν από την ανάλυση ή την απόδοση των δεδομένων της. Ένας μικρός wrapper κάνει το πραγματικό πρόβλημα ορατό στα αρχεία καταγραφής του διακομιστή:

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

Μην καταγράφετε διαπιστευτήρια πρόσβασης, cookies, headers εξουσιοδότησης, κωδικούς πρόσβασης βάσης δεδομένων ή πλήρεις URL που περιέχουν μυστικά. Ένας κωδικός κατάστασης, το όνομα του στόχου του αιτήματος, ένα αναγνωριστικό συσχέτισης και ένα απολυμαντικό μήνυμα σφάλματος είναι συνήθως αρκετά για να εντοπίσετε την αποτυχημένη εξάρτηση.

Βήμα 3: Ελέγξτε τις μεταβλητές περιβάλλοντος και το όριο server/client

Εάν η ίδια δέσμευση (commit) λειτουργεί τοπικά αλλά επιστρέφει σφάλμα 500 μετά την ανάπτυξη, συγκρίνετε τα περιβάλλοντα πριν αλλάξετε τη λογική της εφαρμογής. Επιβεβαιώστε ότι κάθε απαιτούμενη μεταβλητή πλευράς διακομιστή υπάρχει στον στόχο ανάπτυξης και ότι η τιμή δείχνει σε μια υπηρεσία προσβάσιμη από αυτόν τον χρόνο εκτέλεσης. Ένα τοπικό αρχείο .env δεν αποδεικνύει ότι η ανάπτυξη παραγωγής έχει τις ίδιες τιμές.

Στη συνέχεια, επιθεωρήστε τα όρια των component. Τα Server Components του Next.js είναι η προεπιλογή στο App Router, ενώ ο διαδραστικός κώδικας που χρειάζεται κατάσταση, effects, χειρισμό συμβάντων ή APIs αποκλειστικά για το πρόγραμμα περιήγησης ανήκει σε ένα Client Component. Το επίσημο εκπαιδευτικό υλικό του Next.js δείχνει τη μετακίνηση ενός component που χρησιμοποιεί useState πίσω από μια οδηγία 'use client'. Ορισμένα λάθη ορίων εντοπίζονται κατά τη μεταγλώττιση αντί να γίνουν σφάλμα 500, αλλά ο αποκλεισμός τους σας εμποδίζει να αντιμετωπίσετε ένα σφάλμα δομής κώδικα ως διακοπή φιλοξενίας.

Ελέγξτε επίσης οποιοδήποτε πακέτο αποκλειστικά για τον διακομιστή που υποθέτει μια συγκεκριμένη δυνατότητα Node.js, διάταξη συστήματος αρχείων, εγγενές binary ή περιβάλλον δικτύου. Μια εξάρτηση μπορεί να λειτουργεί σε ένα μηχάνημα και να αποτυγχάνει σε έναν άλλο χρόνο εκτέλεσης εάν αυτές οι παραδοχές διαφέρουν.

Βήμα 4: Προσθέστε τη σωστή διαχείριση σφαλμάτων αντί να κρύβετε την εξαίρεση

Μόλις γνωρίζετε την αιτία, αποφασίστε εάν το σφάλμα είναι αναμενόμενο ή μη αναμενόμενο. Ένα λείπον αρχείο μπορεί να αξίζει μια απόκριση not-found. Μια αποτυχία επικύρωσης μπορεί να αξίζει ένα κανονικό μήνυμα. Μια μη αναμενόμενη εξαίρεση πρέπει να καταγράφεται και να επιτρέπεται να φτάσει σε ένα error boundary αντί να μετατρέπεται σιωπηλά σε κενά δεδομένα που χαλάνε κάπου αλλού.

Το Next.js τεκμηριώνει το ειδικό αρχείο error.tsx ως error boundary τμήματος διαδρομής για μη αναμενόμενα σφάλματα. Το component του είναι ένα Client Component και μπορεί να προσφέρει μια επανάληψη μέσω της παρεχόμενης συνάρτησης reset. Ο επίσημος οδηγός διαχείρισης σφαλμάτων του Next.js δείχνει επίσης τη χρήση του notFound() όταν ένα ζητούμενο πόρο δεν υπάρχει.

'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 βελτιώνει αυτό που βλέπει ο χρήστης· δεν διορθώνει την υποκείμενη εξαίρεση. Διατηρήστε το αρχείο καταγραφής πλευράς διακομιστή που εντοπίζει την αιτία και μην εκθέτετε ευαίσθητα stack traces ή μυστικά στο UI.

Βήμα 5: Επαληθεύστε τη διόρθωση σε μια έκδοση παραγωγής

Ένας διακομιστής ανάπτυξης είναι απαραίτητος για τη διάγνωση, αλλά δεν είναι η τελική δοκιμή. Αφού η διαδρομή λειτουργεί τοπικά, εκτελέστε μια έκδοση παραγωγής με τον package manager του έργου σας, ξεκινήστε τη σε λειτουργία παραγωγής όταν είναι εφικτό και ζητήστε την ίδια διαδρομή με τις ίδιες σχετικές συνθήκες δεδομένων. Στη συνέχεια, επαληθεύστε το αναπτυγμένο περιβάλλον με ανοιχτά τα αρχεία καταγραφής χρόνου εκτέλεσης.

npm run build
npm start

Εάν η πλατφόρμα φιλοξενίας σας δημιουργεί έκδοση διαφορετικά από τον φορητό υπολογιστή σας, δοκιμάστε επίσης μια έκδοση προεπισκόπησης πριν προωθήσετε την αλλαγή. Μια διόρθωση είναι αξιόπιστη μόνο όταν η διαδρομή επιστρέφει την αναμενόμενη κατάσταση, αποδίδει το αναμενόμενο περιεχόμενο και δεν εμφανίζεται νέα εξαίρεση διακομιστή για αυτό το αίτημα.

Πώς να επιβεβαιώσετε ότι το σφάλμα 500 έχει πράγματι διορθωθεί

• Η URL που αποτυγχάνει φορτώνει επανειλημμένα χωρίς απόκριση HTTP 500.
• Το τερματικό του διακομιστή ή τα αρχεία καταγραφής χρόνου εκτέλεσης παραγωγής δεν εμφανίζουν πλέον την αρχική εξαίρεση.
• Η ίδια διόρθωση επιβιώνει το npm run build και μια εκτέλεση σε λειτουργία παραγωγής ή μια έκδοση προεπισκόπησης.
• Οι απαιτούμενες μεταβλητές περιβάλλοντος υπάρχουν στο περιβάλλον όπου συνέβη αρχικά η αποτυχία.
• Οι αποτυχίες εξωτερικού API ή βάσης δεδομένων παράγουν πλέον μια ελεγχόμενη διαδρομή σφάλματος αντί για μια ανεξήγητη κατάρρευση.
• Ο διαδραστικός κώδικας αποκλειστικά για το πρόγραμμα περιήγησης βρίσκεται μέσα σε Client Components, ενώ τα μυστικά και η προνομιακή πρόσβαση σε δεδομένα παραμένουν στον διακομιστή.
• Ένα όριο error.tsx παρέχει στους χρήστες μια λογική εναλλακτική λύση για μη αναμενόμενες αποτυχίες τμήματος διαδρομής.

Εάν εξακολουθεί να αποτυγχάνει

Μειώστε τη διαδρομή μέχρι να σταματήσει να αποτυγχάνει. Αντικαταστήστε προσωρινά μία εξάρτηση τη φορά με μια γνωστά ασφαλή τιμή: πρώτα την κλήση βάσης δεδομένων, μετά το εξωτερικό API, μετά την ταυτοποίηση ή την αναζήτηση συνεδρίας, μετά τα child components. Η πρώτη λειτουργία που αφαιρείται και κάνει το σφάλμα 500 να εξαφανιστεί εντοπίζει την περιοχή προς διερεύνηση. Επαναφέρετε κάθε εξάρτηση μετά τη δοκιμή αντί να αφήσετε ψεύτικα δεδομένα στην τελική εφαρμογή.

Για ένα πρόβλημα αποκλειστικά στην παραγωγή, συγκρίνετε την ακριβή αναπτυγμένη δέσμευση, τη διαμόρφωση Node/χρόνου εκτέλεσης, τις μεταβλητές περιβάλλοντος, την προσβασιμότητα δικτύου και τις εκδόσεις εξαρτήσεων. Εάν η πλατφόρμα αναφέρει έναν κωδικό σφάλματος συγκεκριμένο για τον πάροχο, χρησιμοποιήστε την επίσημη τεκμηρίωση του παρόχου για αυτόν τον ακριβή κωδικό αντί να υποθέσετε ότι κάθε σφάλμα 500 έχει την ίδια αιτία.

Ο βασικός κανόνας αντιμετώπισης προβλημάτων είναι απλός: θεωρήστε το «Εσωτερικό Σφάλμα 500» ως το σύμπτωμα. Η χρήσιμη απόδειξη είναι η εξαίρεση πλευράς διακομιστή που συνέβη αμέσως πριν από αυτό. Βρείτε πρώτα αυτήν την εξαίρεση, κάντε την αποτυχημένη εξάρτηση ρητή, διορθώστε το περιβάλλον ή το όριο κώδικα που την προκάλεσε και επαληθεύστε το αποτέλεσμα στον ίδιο χρόνο εκτέλεσης όπου συνέβη το πρόβλημα.