Πώς να διορθώσετε μια κενή λευκή σελίδα στην εφαρμογή σας

Μια κενή λευκή σελίδα σχεδόν πάντα σημαίνει ένα από δύο: η JavaScript της εφαρμογής κόλλησε πριν σχεδιάσει οτιδήποτε, ή η JavaScript δεν φορτώθηκε καθόλου. Ανοίξτε την κονσόλα του browser (δεξί κλικ → Επιθεώρηση → Κονσόλα), διαβάστε το πρώτο κόκκινο σφάλμα και μετά ελέγξτε την καρτέλα Network για αρχεία που απέτυχαν να φορτώσουν. Οι περισσότερες αιτίες είναι μια μεταβλητή περιβάλλοντος που λείπει, λάθος base path, ένα build που δεν ολοκληρώθηκε ή ένα κόλλημα σε ένα component.

Αυτός ο οδηγός καλύπτει εφαρμογές single-page με React, Vue ή παρόμοια frameworks (συμπεριλαμβανομένων εφαρμογών από builders με AI), που είναι όπου οι κενές σελίδες είναι πιο συχνές.

Γιατί η σελίδα είναι λευκή

Μια σύγχρονη εφαρμογή single-page (SPA) στέλνει στον browser ένα σχεδόν κενό αρχείο HTML, περίπου έτσι:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Έπειτα η JavaScript χτίζει ολόκληρη τη σελίδα μέσα σε αυτό το κενό div. Αν το script αποτύχει να φορτώσει, ή πετάξει σφάλμα πριν σχεδιάσει, το div μένει κενό και βλέπετε λευκό. Η σελίδα δεν είναι «σπασμένη» με ορατό τρόπο· απλώς δεν σχεδιάστηκε ποτέ.

Γι' αυτό η διόρθωση ξεκινά πάντα στα εργαλεία προγραμματιστή, όχι στη σελίδα.

Βήμα 1: Διαβάστε την κονσόλα

Ανοίξτε τα εργαλεία προγραμματιστή: δεξί κλικ στη σελίδα και Επιθεώρηση, ή F12 (Cmd+Option+I σε Mac). Πηγαίνετε στην καρτέλα Console και κάντε ανανέωση.

Κοιτάξτε το πρώτο κόκκινο σφάλμα· τα επόμενα είναι συχνά παρενέργειες. Αυτό που λέει δείχνει την αιτία:

Αντιγράψτε ολόκληρο το κείμενο του σφάλματος, με το όνομα αρχείου και τον αριθμό γραμμής. Αν χρησιμοποιείτε builder με AI, επικολλήστε το κατευθείαν στο chat.

Βήμα 2: Ελέγξτε ότι τα αρχεία φορτώθηκαν

Ανοίξτε την καρτέλα Network, τσεκάρετε Disable cache και κάντε ανανέωση. Κοιτάξτε τα αιτήματα για αρχεία .js και .css.

• Κατάσταση 404 σε αρχείο JavaScript: η σελίδα ζητά αρχείο που δεν υπάρχει στον server.
• Κατάσταση 200 αλλά τύπος text/html: ο server επέστρεψε σελίδα (συχνά το ίδιο το index.html, λόγω ενός SPA fallback) αντί για το script. Η ίδια βασική αιτία: το αρχείο δεν βρίσκεται εκεί που το περιμένει η σελίδα.

Συνηθισμένοι λόγοι:

Λάθος base path. Αν η εφαρμογή σερβίρεται από υποφάκελο, όπως example.com/app/, αλλά χτίστηκε για να φορτώνει αρχεία από /assets/..., κάθε αίτημα script χάνεται. Στο Vite αυτό είναι η επιλογή base στο vite.config· στο Create React App είναι το πεδίο homepage· στο Next.js είναι το basePath. Πρέπει να ταιριάζει με το σημείο όπου πραγματικά σερβίρεται η εφαρμογή.

Παλιό index.html. Τα εργαλεία build δίνουν στα αρχεία ονόματα με hash περιεχομένου, όπως index-a1b2c3.js. Μετά από νέο deploy, το παλιό αρχείο έχει φύγει. Αν ένας browser ή CDN έχει ακόμα αποθηκευμένο το παλιό index.html, ζητά το παλιό αρχείο και δεν παίρνει τίποτα. Μια σκληρή ανανέωση (Cmd+Shift+R ή Ctrl+Shift+R) το επιβεβαιώνει. Η μακροπρόθεσμη λύση είναι να σερβίρεται το index.html με σύντομη ή καθόλου κρυφή μνήμη, ενώ τα αρχεία με hash κρατιούνται για πολύ.

Το build δεν ολοκληρώθηκε ή δεν έγινε deploy. Αν το build απέτυχε, ο host μπορεί να σερβίρει παλιό ή άδειο φάκελο αποτελέσματος. Ελέγξτε το log του build για σφάλματα.

Δημοσιεύεται λάθος φάκελος. Ο host πρέπει να σερβίρει το αποτέλεσμα του build (συνήθως dist ή build), όχι τον φάκελο του πηγαίου κώδικα. Αν σερβίρεται ο πηγαίος κώδικας, παίρνετε ένα index.html που δείχνει στο /src/main.tsx, το οποίο ο browser δεν μπορεί να τρέξει.

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

Οι εφαρμογές front end συχνά διαβάζουν ρυθμίσεις όπως μια διεύθυνση API ή ένα δημόσιο κλειδί κατά τη στιγμή του build. Αν μια μεταβλητή λείπει στο ζωντανό build, κώδικας όπως το createClient(undefined, undefined) σκάει αμέσως και η σελίδα γίνεται λευκή.

Πράγματα που πρέπει να ξέρετε:

• Στο Vite, μόνο οι μεταβλητές με πρόθεμα VITE_ είναι διαθέσιμες στον κώδικα του browser, και διαβάζονται ως import.meta.env.VITE_NAME. Στο Create React App είναι REACT_APP_· στο Next.js, NEXT_PUBLIC_.
• Αυτές οι τιμές ενσωματώνονται τη στιγμή του build. Η προσθήκη μιας μεταβλητής μετά το build δεν κάνει τίποτα μέχρι να ξαναχτίσετε και να ξανακάνετε deploy.
• Η προεπισκόπηση ή ο τοπικός σας υπολογιστής μπορεί να έχει αρχείο .env που δεν έχει το build παραγωγής. Ορίστε τις ίδιες μεταβλητές στον host.
• Ό,τι έχει αυτά τα προθέματα καταλήγει σε δημόσια JavaScript. Βάζετε μόνο δημόσιες τιμές εκεί, ποτέ μυστικά κλειδιά.

Ένα γρήγορο τεστ: ψάξτε στο σφάλμα της κονσόλας για undefined δίπλα σε όνομα ρύθμισης, ή ρωτήστε:

Η δημοσιευμένη εφαρμογή δείχνει κενή σελίδα. Κάνε λίστα με κάθε μεταβλητή περιβάλλοντος που διαβάζει το front end, έλεγξε ποιες λείπουν ή είναι κενές στο ζωντανό build, και κάνε την εφαρμογή να δείχνει καθαρό μήνυμα σφάλματος αντί για κενή σελίδα όταν λείπει μία.

Βήμα 4: Διορθώστε το κόλλημα

Αν η κονσόλα δείχνει ένα συνηθισμένο σφάλμα JavaScript, ο κώδικας κόλλησε κατά την απόδοση. Τυπικές αιτίες σε εφαρμογές με AI:

• Τα δεδομένα δεν έχουν φορτωθεί ακόμα. Ένα component διαβάζει το user.name πριν φτάσει το user. Η λύση είναι μια κατάσταση φόρτωσης, ή optional chaining (user?.name).
• Κενά δεδομένα. Ένας νέος λογαριασμός δεν έχει εγγραφές, και ο κώδικας υποθέτει ότι η λίστα έχει τουλάχιστον ένα στοιχείο.
• Απροσδόκητο σχήμα δεδομένων. Ένα API επέστρεψε ένα αντικείμενο σφάλματος αντί για τη λίστα που περίμενε ο κώδικας.
• Ένα import που λείπει αφού μετονομάστηκε ή μετακινήθηκε ένα αρχείο.
• Χρήση API που υπάρχει μόνο στον browser κατά το server-side rendering, όπως window ή localStorage σε server component του Next.js.

Δώστε στο AI το πλήρες σφάλμα, τη σελίδα και με ποιον λογαριασμό ήσασταν συνδεδεμένοι:

Η σελίδα Dashboard είναι κενή για νέους χρήστες. Κονσόλα: TypeError: Cannot read properties of undefined (reading 'map') στο ProjectList.tsx:18. Δουλεύει για τον λογαριασμό μου, που έχει projects. Διόρθωσε το ώστε ένας άδειος λογαριασμός να δείχνει «Δεν υπάρχουν projects ακόμα», και έλεγξε έναν νέο λογαριασμό στην προεπισκόπηση.

Βήμα 5: Προσθέστε error boundary

Στο React, ένα component που κολλάει μπορεί να αφαιρέσει ολόκληρη την εφαρμογή, και γι' αυτό ένα μικρό σφάλμα δίνει εντελώς κενή σελίδα. Ένα error boundary είναι component που πιάνει σφάλματα απόδοσης κάτω από αυτό και δείχνει εναλλακτικό περιεχόμενο.

Πρόσθεσε ένα error boundary γύρω από τις κύριες διαδρομές που δείχνει «Κάτι πήγε στραβά» με κουμπί Ανανέωση, και καταγράφει το σφάλμα στην κονσόλα. Κράτα την κεφαλίδα και την πλοήγηση έξω από αυτό ώστε να εμφανίζονται ακόμα.

Δεν διορθώνει το σφάλμα, αλλά οι επισκέπτες βλέπουν ένα μήνυμα αντί για κενή οθόνη, και εσείς βλέπετε πού χάλασε.

Βήμα 6: Καμία καταγραφή σφάλματος, αλλά κενή σελίδα

Αν η κονσόλα είναι καθαρή και τα scripts φορτώνουν:

• Ελέγξτε την καρτέλα Elements. Υπάρχει περιεχόμενο μέσα στο <div id="root">; Αν ναι, αποδίδεται αλλά είναι αόρατο: λευκό κείμενο σε λευκό φόντο, opacity: 0, display: none, ή ένα στοιχείο πλήρους οθόνης που το καλύπτει.
• Ελέγξτε τον router. Αν καμία διαδρομή δεν ταιριάζει με το τρέχον URL και δεν υπάρχει διαδρομή «δεν βρέθηκε», μερικοί router δεν αποδίδουν τίποτα. Προσθέστε catch-all route που δείχνει σελίδα 404.
• Ελέγξτε το σημείο τοποθέτησης. Ο κώδικας πρέπει να τοποθετείται σε στοιχείο που υπάρχει. Αν το index.html έχει id="app" και ο κώδικας ψάχνει root, δεν εμφανίζεται τίποτα (και το React συνήθως καταγράφει σφάλμα).
• Ελέγξτε μια επέκταση του browser. Δοκιμάστε ιδιωτικό παράθυρο. Οι ad blockers μερικές φορές μπλοκάρουν scripts με ονόματα όπως analytics ή ads.

Κενή μόνο μετά την ανανέωση σελίδας;

Αν η αρχική σελίδα δουλεύει αλλά η ανανέωση του /dashboard δείχνει κενή σελίδα ή 404, ο server δεν ξέρει να στέλνει το index.html για διαδρομές της εφαρμογής. Αυτό είναι πρόβλημα δρομολόγησης fallback, που καλύπτεται στο πώς να διορθώσετε σφάλματα 404 μετά το deploy.

Συνηθισμένα λάθη

• Διαβάζετε το τελευταίο σφάλμα αντί για το πρώτο. Η πρώτη κόκκινη γραμμή είναι συνήθως η αιτία.
• Ορίζετε μεταβλητές περιβάλλοντος χωρίς να ξαναχτίσετε. Οι μεταβλητές του front end καθορίζονται τη στιγμή του build.
• Δοκιμάζετε μόνο με τον δικό σας λογαριασμό. Τα κολλήματα σε άδειους λογαριασμούς είναι από τις πιο συνηθισμένες αιτίες κενής σελίδας.
• Υποθέτετε ότι το deploy πέτυχε. Ελέγξτε το log του build πριν ψάξετε στον κώδικα.
• Κατηγορείτε πάντα την κρυφή μνήμη του browser. Μια σκληρή ανανέωση το αποκλείει σε δευτερόλεπτα· αν η σελίδα είναι ακόμα κενή, είναι κάτι άλλο.

Κενές σελίδες στο Mythex

Αν η Προεπισκόπηση είναι κενή, πρώτα ελέγξτε ότι η εφαρμογή τρέχει (ανοίξτε Κώδικας → τερματικό), και μετά ζητήστε από το Mythex να ξεκινήσει τον σωστό server, κάντε κλικ στο Ανανέωση στη γραμμή εργαλείων της προεπισκόπησης, ή χρησιμοποιήστε /fix. Για ένα κενό δημοσιευμένο URL, η τεκμηρίωση προτείνει να περιμένετε ένα λεπτό και να κάνετε σκληρή ανανέωση, να επιβεβαιώσετε ότι οι μεταβλητές περιβάλλοντος και η βάση ρυθμίστηκαν πριν τη δημοσίευση, και να ελέγξετε το όριο φιλοξενίας σας. Θυμηθείτε ότι μια δημοσιευμένη εφαρμογή είναι στιγμιότυπο: μετά από διόρθωση, δημοσιεύστε ξανά. Αν μια αλλαγή το προκάλεσε, το Επαναφορά σε αυτό το σημείο στην τελευταία καλή απάντηση γυρίζει το project πίσω. Δείτε Αντιμετώπιση προβλημάτων και Αντιμετώπιση προβλημάτων δημοσίευσης στην τεκμηρίωση, και τον γενικό μας οδηγό για αποσφαλμάτωση εφαρμογής φτιαγμένης με AI.

Λίστα ελέγχου για κενή σελίδα

• Διαβάστηκε το πρώτο κόκκινο σφάλμα στην Κονσόλα
• Ελέγχθηκαν στην καρτέλα Network τα αρχεία .js/.css που δίνουν 404 ή HTML
• Το base path ταιριάζει με το σημείο όπου σερβίρεται η εφαρμογή
• Το build ολοκληρώθηκε, και ο φάκελος αποτελέσματος είναι αυτός που δημοσιεύεται
• Όλες οι μεταβλητές περιβάλλοντος του front end έχουν οριστεί στο ζωντανό build, και έγινε νέο build
• Το κόλλημα διορθώθηκε, και για άδεια και νέα λογαριασμούς
• Υπάρχει error boundary ώστε μελλοντικά σφάλματα να δείχνουν μήνυμα
• Υπάρχει catch-all route για άγνωστες διευθύνσεις
• Δοκιμάστηκε μετά από σκληρή ανανέωση και σε ιδιωτικό παράθυρο

Ερωτήσεις