Kako popraviti prazan bijeli ekran u web aplikaciji

Prazan bijeli ekran gotovo uvijek znači jedno od dvoje: JavaScript aplikacije se srušio prije nego što je išta nacrtao ili se JavaScript uopće nije učitao. Otvorite konzolu preglednika (desni klik → Inspect → Console), pročitajte prvu crvenu grešku, a zatim provjerite karticu Network za datoteke koje se nisu učitale. Većina uzroka je varijabla okruženja koja nedostaje, pogrešna osnovna putanja, build koji nije završio ili rušenje jedne komponente.

Ovaj vodič pokriva single-page aplikacije izgrađene s Reactom, Vueom ili sličnim okvirima (uključujući aplikacije koje su napravili AI graditelji), gdje su prazni ekrani najčešći.

Zašto je stranica bijela

Moderna single-page aplikacija (SPA) šalje pregledniku gotovo praznu HTML datoteku, otprilike ovakvu:

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

JavaScript zatim cijelu stranicu gradi unutar tog praznog div-a. Ako se skripta ne učita ili baci grešku prije renderiranja, div ostaje prazan i vidite bijelo. Stranica nije „pokvarena” na vidljiv način; jednostavno nikad nije iscrtana.

Zato popravak uvijek počinje u alatima za razvojne programere, a ne na samoj stranici.

Korak 1: Pročitajte konzolu

Otvorite alate za razvojne programere: desni klik na stranicu i odaberite Inspect ili pritisnite F12 (Cmd+Option+I na Macu). Idite na karticu Console i osvježite stranicu.

Pogledajte prvu crvenu grešku; kasnije su često posljedice. Što ona kaže, pokazuje uzrok:

Kopirajte cijeli tekst greške, uključujući ime datoteke i broj retka. Ako koristite AI graditelj, zalijepite ga izravno u chat.

Korak 2: Provjerite jesu li se datoteke učitale

Otvorite karticu Network, označite Disable cache i osvježite. Pogledajte zahtjeve za .js i .css datoteke.

• Status 404 na JavaScript datoteci: stranica traži datoteku koje nema na poslužitelju.
• Status 200, ali tip je text/html: poslužitelj je vratio stranicu (često sam index.html, zbog SPA povrata) umjesto skripte. Isti je korijen problema: datoteka nije tamo gdje je stranica očekuje.

Uobičajeni razlozi:

Pogrešna osnovna putanja. Ako se aplikacija služi iz podmape, poput example.com/app/, ali je izgrađena da učitava datoteke s /assets/..., svaki zahtjev za skriptu promašuje. U Viteu je to opcija base u vite.config; u Create React Appu polje homepage; u Next.js-u basePath. Mora odgovarati mjestu na kojem se aplikacija zaista služi.

Zastarjeli index.html. Alati za build daju datotekama imena s hashom sadržaja, poput index-a1b2c3.js. Nakon novog deployja stara datoteka nestaje. Ako preglednik ili CDN još ima stari index.html u predmemoriji, traži staru datoteku i ne dobiva ništa. Tvrdo osvježavanje (Cmd+Shift+R ili Ctrl+Shift+R) to potvrđuje. Dugoročno rješenje je poslužiti index.html s kratkim ili nikakvim cache zaglavljem, dok se datoteke s hashom mogu čuvati u predmemoriji dugo.

Build nije završio ili nije deployan. Ako je build pao, host možda poslužuje staru ili praznu izlaznu mapu. Provjerite log builda za greške.

Objavljena je pogrešna mapa. Host mora poslužiti izlaz builda (obično dist ili build), a ne izvornu mapu projekta. Ako poslužite izvor, dobit ćete index.html koji pokazuje na /src/main.tsx, a to preglednici ne mogu pokrenuti.

Korak 3: Provjerite varijable okruženja

Frontend aplikacije često pri buildu čitaju postavke poput URL-a API-ja ili javnog ključa. Ako varijabla nedostaje u živom buildu, kod poput createClient(undefined, undefined) odmah baca grešku i stranica postaje bijela.

Što treba znati:

• U Viteu su varijable s prefiksom VITE_ dostupne u kodu za preglednik i čitaju se kao import.meta.env.VITE_NAME. U Create React Appu je prefiks REACT_APP_; u Next.js-u NEXT_PUBLIC_.
• Ove vrijednosti se ugrađuju pri buildu. Dodavanje varijable nakon builda ne čini ništa dok ne ponovno izgradite i deployate.
• Preview ili vaše lokalno računalo mogu imati .env datoteku koju produkcijski build nema. Postavite iste varijable na hostu.
• Sve s tim prefiksima završava u javnom JavaScriptu. Stavljajte tamo samo javne vrijednosti, nikad tajne ključeve.

Brz test: potražite u grešci u konzoli undefined u blizini naziva postavke ili pitajte:

Objavljena aplikacija prikazuje prazan ekran. Popiši svaku varijablu okruženja koju frontend čita, provjeri koje nedostaju ili su prazne u živom buildu i učini da aplikacija prikaže jasnu poruku o grešci umjesto praznog ekrana kad neka nedostaje.

Korak 4: Popravite rušenje

Ako konzola prikazuje normalnu JavaScript grešku, kod se srušio tijekom renderiranja. Tipični uzroci u aplikacijama izgrađenim uz AI:

• Podaci još nisu učitani. Komponenta čita user.name prije nego što je stigao user. Rješenje je stanje učitavanja ili optional chaining (user?.name).
• Prazni podaci. Novi račun nema zapise, a kod pretpostavlja da lista ima barem jednu stavku.
• Neočekivani oblik podataka. API je vratio objekt greške umjesto liste koju je kod očekivao.
• Import koji nedostaje nakon što je datoteka preimenovana ili premještena.
• Korištenje API-ja samo za preglednik tijekom renderiranja na poslužitelju, poput window ili localStorage u Next.js server komponenti.

Dajte AI-ju punu grešku, stranicu i račun s kojim ste bili prijavljeni:

Stranica Dashboard je prazna za nove korisnike. Konzola: TypeError: Cannot read properties of undefined (reading 'map') na ProjectList.tsx:18. Radi za moj račun, koji ima projekte. Popravi da prazan račun prikaže „Još nema projekata” i provjeri novi račun u pregledu.

Korak 5: Dodajte error boundary

U Reactu jedna komponenta koja se sruši može ukloniti cijelu aplikaciju, zbog čega mala greška daje potpuno praznu stranicu. Error boundary je komponenta koja hvata greške pri renderiranju ispod sebe i umjesto toga prikazuje zamjenu.

Dodaj error boundary oko glavnih ruta koji prikazuje „Nešto nije u redu” s gumbom Reload i bilježi grešku u konzolu. Zaglavlje i navigaciju drži izvan njega da se i dalje prikazuju.

Ne popravlja grešku, ali posjetitelji vide poruku umjesto praznog ekrana, a vi vidite gdje je došlo do kvara.

Korak 6: Nema grešaka, a ekran je ipak prazan

Ako je konzola čista i skripte se učitavaju:

• Provjerite karticu Elements. Ima li sadržaja unutar <div id="root">? Ako da, renderira se, ali nevidljivo: bijeli tekst na bijeloj pozadini, opacity: 0, display: none ili element preko cijelog ekrana koji ga prekriva.
• Provjerite router. Ako nijedna ruta ne odgovara trenutnom URL-u i nema rute „nije pronađeno”, neki routeri ne prikazuju ništa. Dodajte catch-all rutu koja prikazuje stranicu 404.
• Provjerite točku montiranja. Kod se mora montirati u element koji postoji. Ako index.html ima id="app", a kod traži root, ništa se ne pojavljuje (a React obično zapisuje grešku).
• Provjerite dodatak preglednika. Pokušajte u privatnom prozoru. Blokatori oglasa ponekad blokiraju skripte s imenima poput analytics ili ads.

Prazno tek nakon osvježavanja stranice?

Ako početna stranica radi, ali osvježavanje /dashboard prikazuje prazan ekran ili 404, poslužitelj ne zna da za rute aplikacije treba poslati index.html. To je problem SPA povrata, pokriven u kako popraviti 404 greške nakon deployja.

Česte greške

• Čitanje zadnje greške umjesto prve. Prva crvena linija obično je uzrok.
• Postavljanje varijabli okruženja bez ponovnog builda. Frontend varijable su fiksirane pri buildu.
• Testiranje samo s vlastitim računom. Rušenja za prazne račune jedan su od najčešćih uzroka praznih ekrana.
• Pretpostavka da je deploy uspio. Provjerite log builda prije nego što debugirate kod.
• Okrivljavanje predmemorije preglednika za sve. Tvrdo osvježavanje to isključi za nekoliko sekundi; ako je stranica i dalje prazna, uzrok je nešto drugo.

Prazne stranice u Mythexu

Ako je pregled prazan, prvo provjerite radi li aplikacija (otvorite Code → terminal), zatim zamolite Mythex da pokrene ispravan server, kliknite Refresh u alatnoj traci pregleda ili upišite /fix. Za prazan objavljen URL dokumentacija predlaže da pričekate minutu i tvrdo osvježite, potvrdite da su varijable okruženja i baza postavljene prije objave te provjerite svoju kvotu hostinga. Imajte na umu da je objavljena aplikacija snimka: nakon ispravka ponovno objavite. Ako je promjena uzrokovala problem, Vrati na ovu točku na zadnjem dobrom odgovoru vraća projekt unatrag. Pogledajte Rješavanje problema i Rješavanje problema s objavom u dokumentaciji te naš opći vodič o otklanjanju grešaka u aplikaciji izgrađenoj uz AI.

Popis za prazan ekran

• Pročitana prva crvena greška u konzoli
• Provjerene .js i .css datoteke u kartici Network koje daju 404 ili vraćaju HTML
• Osnovna putanja odgovara mjestu na kojem se aplikacija služi
• Build je završio i izlazna mapa builda je ono što se objavljuje
• Sve varijable okruženja za frontend postavljene na živom buildu, zatim ponovno izgrađeno
• Rušenje popravljeno, uključujući za prazne i nove račune
• Error boundary postavljen da buduća rušenja prikažu poruku
• Catch-all ruta za nepoznate URL-ove
• Testirano nakon tvrdog osvježavanja i u privatnom prozoru

Pitanja