Kā novērst tukšu baltu lapu tīmekļa lietotnē

Tukša balta lapa gandrīz vienmēr nozīmē vienu no diviem: vienas lapas lietotnes JavaScript avarēja, pirms kaut ko uzzīmēja, vai JavaScript vispār nekad neielādējās. Atver pārlūka konsoli (ar peles labo pogu → Inspect → Console), izlasi pirmo sarkano kļūdu un pēc tam pārbaudi cilni Network, vai nav failu, kas neielādējās. Visbiežākie cēloņi ir trūkstošs vides mainīgais, nepareizs bāzes ceļš, nepabeigta būve vai avārija vienā komponentā.

Šis ceļvedis aptver vienas lapas lietotnes, kas būvētas ar React, Vue vai līdzīgiem ietvariem (tostarp AI veidotāju lietotnes), jo tieši tur tukšas lapas ir visbiežākās.

Kāpēc lapa ir balta

Mūsdienu vienas lapas lietotne (SPA) pārlūkam nosūta gandrīz tukšu HTML failu, aptuveni šādu:

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

Pēc tam JavaScript veido visu lapu šajā tukšajā div. Ja skripts neielādējas vai pirms renderēšanas met kļūdu, div paliek tukšs, un redzi baltu. Lapa nav „salauzta” redzamā veidā; tā vienkārši nekad netika uzzīmēta.

Tāpēc labojums vienmēr sākas izstrādātāju rīkos, nevis pašā lapā.

1. solis: izlasi konsoli

Atver izstrādātāju rīkus: ar peles labo pogu uzklikšķini lapā un izvēlies Inspect, vai nospied F12 (Cmd+Option+I Mac datorā). Dodies uz cilni Console un atsvaidzini lapu.

Skaties uz pirmo sarkano kļūdu; vēlākās bieži ir blakusefekti. Tas, ko tā saka, norāda uz cēloni:

Nokopē pilno kļūdas tekstu, tostarp faila nosaukumu un rindas numuru. Ja izmanto AI veidotāju, ielīmē to tieši tērzēšanā.

2. solis: pārbaudi, vai faili ielādējās

Atver cilni Network, atzīmē Disable cache un atsvaidzini lapu. Skaties pieprasījumus .js un .css failiem.

• Statuss 404 JavaScript failam: lapa prasa failu, kas serverī nav.
• Statuss 200, bet tips text/html: serveris atgrieza lapu (bieži pašu index.html, jo SPA atkāpes dēļ), nevis skriptu. Tas pats pamatcēlonis: fails nav tur, kur lapa to sagaida.

Biežākie iemesli:

Nepareizs bāzes ceļš. Ja lietotne tiek pasniegta no apakšmapes, piemēram, example.com/app/, bet būvēta tā, lai ielādētu failus no /assets/..., katrs skripta pieprasījums neatrod failu. Vite tas ir opcija base konfigurācijā vite.config; Create React App tas ir lauks homepage; Next.js tas ir basePath. Tam jāsakrīt ar vietu, kur lietotne faktiski tiek pasniegta.

Novecojis index.html. Būves rīki failiem dod nosaukumus ar satura jaucējkodu, piemēram, index-a1b2c3.js. Pēc jaunas izvietošanas vecais fails pazūd. Ja pārlūkā vai CDN joprojām ir kešots vecais index.html, tas pieprasa veco failu un nesaņem neko. Cieta atsvaidzināšana (Cmd+Shift+R vai Ctrl+Shift+R) to apstiprina. Ilgtermiņa labojums ir pasniegt index.html ar īsu vai nekeša galveni, kamēr jaucējkodētie faili tiek kešoti ilgi.

Būve nepabeidzās vai nebija izvietota. Ja būve neizdevās, hostings var pasniegt vecu vai tukšu izvades mapi. Pārbaudi būves žurnālu, vai nav kļūdu.

Publicēta nepareiza mape. Hostingam jāpasniedz būves izvade (parasti dist vai build), nevis projekta pirmkoda mape. Pirmkoda pasniegšana dod index.html, kas norāda uz /src/main.tsx, ko pārlūki nevar palaist.

3. solis: pārbaudi vides mainīgos

Frontend lietotnes bieži nolasa iestatījumus, piemēram, API URL vai publisko atslēgu, būves laikā. Ja dzīvajā būvē mainīgais trūkst, kods createClient(undefined, undefined) uzreiz met kļūdu, un lapa kļūst balta.

Lietas, kas jāzina:

• Vite tikai mainīgie ar priedēkli VITE_ ir pieejami pārlūka kodā, nolasot tos kā import.meta.env.VITE_NAME. Create React App tas ir REACT_APP_; Next.js — NEXT_PUBLIC_.
• Šīs vērtības tiek iekļautas, kad lietotne tiek būvēta. Mainīgā pievienošana pēc būves nedara neko, kamēr neveido un neizvieto vēlreiz.
• Priekšskatījumā vai lokālajā mašīnā var būt .env fails, ko ražošanas būve neredz. Iestati tos pašus mainīgos hostingā.
• Viss ar šiem priedēkliem nonāk publiskā JavaScript. Ieliec tajā tikai publiskas vērtības, nekad slepenās atslēgas.

Ātrs tests: meklē konsoles kļūdā undefined iestatījuma nosaukuma tuvumā vai jautā:

Publicētā lietotne rāda tukšu lapu. Uzskaiti katru vides mainīgo, ko frontend nolasa, pārbaudi, kuri trūkst vai ir tukši dzīvajā būvē, un padari lietotni, kas parāda skaidru kļūdas ziņojumu, nevis tukšu lapu, kad kāds trūkst.

4. solis: novērs avāriju

Ja konsolē ir parasta JavaScript kļūda, kods avarēja renderēšanas laikā. Tipiski cēloņi AI veidotās lietotnēs:

• Dati vēl nav ielādēti. Komponents nolasa user.name, pirms user ir ieradies. Labojums ir ielādes stāvoklis vai neobligāta ķēdēšana (user?.name).
• Tukši dati. Jaunam kontam nav ierakstu, un kods pieņem, ka sarakstā ir vismaz viens vienums.
• Neparedzēta datu forma. API atgrieza kļūdas objektu, nevis sarakstu, ko kods gaidīja.
• Trūkstošs imports pēc tam, kad fails tika pārdēvēts vai pārvietots.
• Pārlūka API izmantošana serverpusējā renderēšanā, piemēram, window vai localStorage Next.js servera komponentē.

Dod AI pilnu kļūdu, lapu un to, kā tu biji pieteicies:

Paneļa lapa ir tukša jaunajiem lietotājiem. Konsole: TypeError: Cannot read properties of undefined (reading 'map') failā ProjectList.tsx:18. Tā darbojas manam kontam, kuram ir projekti. Labo to tā, lai tukšs konts rādītu „Vēl nav projektu”, un pārbaudi jaunu kontu priekšskatījumā.

5. solis: pievieno kļūdu robežu

React vienā avārijā sakošs komponents var noņemt visu lietotni, tāpēc neliela kļūda rada pilnīgi tukšu lapu. Kļūdu robeža (error boundary) ir komponents, kas notver renderēšanas kļūdas zem sevis un parāda rezerves ziņojumu.

Pievieno kļūdu robežu ap galvenajiem maršrutiem, kas parāda „Kaut kas nogāja greizi” ar pogu Pārlādēt un ieraksta kļūdu konsolē. Galvene un navigācija ārpus tās, lai tās joprojām tiktu rādītas.

Tā neizlabo kļūdu, bet apmeklētāji redz ziņojumu, nevis tukšu ekrānu, un tu redzi, kur tas salūza.

6. solis: nav kļūdu, bet joprojām tukšs

Ja konsole ir tīra un skripti ielādējas:

• Pārbaudi cilni Elements. Vai <div id="root"> iekšpusē ir saturs? Ja jā, tas tiek renderēts, bet nav redzams: balts teksts uz balta, opacity: 0, display: none vai pilnekrāna elements, kas to pārklāj.
• Pārbaudi maršrutētāju. Ja neviens maršruts neatbilst pašreizējam URL un nav „nav atrasts” maršruta, daži maršrutētāji neko neparāda. Pievieno visaptverošu maršrutu, kas rāda 404 lapu.
• Pārbaudi montāžas punktu. Kodam jāmontējas elementā, kas eksistē. Ja index.html ir id="app", bet kods meklē root, nekas neparādās (un React parasti reģistrē kļūdu).
• Pārbaudi pārlūka paplašinājumu. Izmēģini privātu logu. Reklāmu bloķētāji dažreiz bloķē skriptus ar tādiem nosaukumiem kā analytics vai ads.

Tukšs tikai pēc lapas atsvaidzināšanas?

Ja sākumlapa darbojas, bet /dashboard atsvaidzināšana rāda tukšu lapu vai 404, serveris nezina, ka jānosūta index.html lietotnes maršrutiem. Tā ir maršrutēšanas atkāpes problēma, ko aptver kā novērst 404 kļūdas pēc izvietošanas.

Biežākās kļūdas

• Lasīt pēdējo kļūdu, nevis pirmo. Pirmā sarkanā rinda parasti ir cēlonis.
• Iestatīt vides mainīgos bez pārbūves. Frontend mainīgie tiek fiksēti būves laikā.
• Testēt tikai ar savu kontu. Avārijas tukšiem kontiem ir viens no biežākajiem tukšas lapas cēloņiem.
• Pieņemt, ka izvietošana izdevās. Pirms koda atkļūdošanas pārbaudi būves žurnālu.
• Vainot pārlūka kešatmiņu visā. Cieta atsvaidzināšana to izslēdz dažās sekundēs; ja lapa joprojām ir tukša, tas ir kaut kas cits.

Tukšas lapas Mythex

Ja priekšskatījums ir tukšs, vispirms pārbaudi, vai lietotne darbojas (atver Code → terminal), tad lūdz Mythex palaist pareizo serveri, noklikšķini Refresh priekšskatījuma rīkjoslā vai izmanto /fix. Tukšam publicētam URL dokumentācija iesaka pagaidīt minūti un veikt cietu atsvaidzināšanu, pārliecināties, ka vides mainīgie un datubāze bija iestatīti pirms publicēšanas, un pārbaudīt savu hostinga kvotu. Atceries, ka publicēta lietotne ir momentuzņēmums: pēc labojuma publicē vēlreiz. Ja izmaiņa to izraisīja, Revert to this point pie pēdējās labās atbildes atgriež projektu. Skaties Problēmu novēršana un Publicēšanas problēmu novēršana dokumentācijā, kā arī mūsu vispārīgo ceļvedi kā atkļūdot ar AI veidotu lietotni.

Tukšas lapas kontrolsaraksts

• Izlasīta pirmā sarkanā kļūda konsolē
• Pārbaudīta cilne Network .js/.css failiem, kas dod 404 vai atgriež HTML
• Bāzes ceļš sakrīt ar vietu, kur lietotne tiek pasniegta
• Būve pabeigta, un publicēta būves izvades mape
• Visi frontend vides mainīgie iestatīti dzīvajā būvē, tad pārbūvēts
• Avārija novērsta, tostarp tukšiem un jauniem kontiem
• Kļūdu robeža ieviesta, lai nākotnes avārijas rādītu ziņojumu
• Visaptverošs maršruts nezināmiem URL
• Pārbaudīts pēc cietas atsvaidzināšanas un privātā logā

Jautājumi