Kako odpraviti prazno belo stran v spletni aplikaciji

Prazna bela stran skoraj vedno pomeni eno od dveh stvari: JavaScript aplikacije se je zrušil, preden je karkoli narisal, ali se JavaScript sploh ni naložil. Odprite konzolo brskalnika (desni klik → Preglej → Konzola), preberite prvo rdečo napako, nato pa preverite zavihek Omrežje za datoteke, ki se niso naložile. Največkrat je vzrok manjkajoča okoljska spremenljivka, napačna osnovna pot, gradnja, ki se ni končala, ali zrušitev ene komponente.

Ta vodnik zajema aplikacije z eno stranjo, zgrajene z React, Vue ali podobnimi ogrodji (vključno z aplikacijami, ki so jih naredila orodja za gradnjo z AI), kjer so prazne strani najpogostejše.

Zakaj je stran bela

Sodobna aplikacija z eno stranjo (SPA) brskalniku pošlje skoraj prazno datoteko HTML, nekako takole:

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

JavaScript nato zgradi celotno stran znotraj tega praznega div. Če se skripta ne naloži ali vrže napako, preden se upodobi, div ostane prazen in vidite belo. Stran ni »pokvarjena« na viden način; preprosto nikoli ni bila narisana.

Zato se popravljanje vedno začne v orodjih za razvijalce, ne na sami strani.

1. korak: preberite konzolo

Odprite orodja za razvijalce: desni klik na stran in izberite Preglej ali pritisnite F12 (Cmd+Option+I na Macu). Pojdite na zavihek Konzola in osvežite stran.

Poglejte prvo rdečo napako; kasnejše so pogosto stranski učinki. Kar piše, kaže na vzrok:

Kopirajte celotno besedilo napake, vključno z imenom datoteke in številko vrstice. Če uporabljate orodje za gradnjo z AI, ga prilepite naravnost v klepet.

2. korak: preverite, ali so se datoteke naložile

Odprite zavihek Omrežje, označite Onemogoči predpomnjenje in osvežite. Poglejte zahteve za datoteke .js in .css.

• Statusna koda 404 pri datoteki JavaScript: stran zahteva datoteko, ki na strežniku ne obstaja.
• Statusna koda 200, vendar je tip text/html: strežnik je vrnil stran (pogosto sam index.html zaradi rezerve SPA) namesto skripte. Isti koren problema: datoteka ni tam, kjer jo stran pričakuje.

Pogosti razlogi:

Napačna osnovna pot. Če je aplikacija streženja iz podmape, na primer example.com/app/, je pa zgrajena tako, da naloži datoteke iz /assets/..., vsaka zahteva za skripto zgreši. V Vite je to možnost base v vite.config; v Create React App polje homepage; v Next.js basePath. Mora se ujemati z mestom, kjer je aplikacija dejansko streženja.

Zastarel index.html. Orodja za gradnjo datotekam dajejo imena z zgoščenko vsebine, kot je index-a1b2c3.js. Po novi objavi stara datoteka izgine. Če brskalnik ali CDN še vedno hrani stari index.html v predpomnilniku, zahteva staro datoteko in ne dobi ničesar. Trdo osveževanje (Cmd+Shift+R ali Ctrl+Shift+R) to potrdi. Dolgoročna rešitev je, da se index.html streže s kratkim ali brez predpomnilnika, medtem ko so datoteke z zgoščenko lahko dolgo predpomnjene.

Gradnja ni končana ali ni bila objavljena. Če gradnja ne uspe, lahko gostitelj streže staro ali prazno izhodno mapo. Preverite dnevnik gradnje za napake.

Objavljena je napačna mapa. Gostitelj mora streči izhod gradnje (običajno dist ali build), ne izvorne mape projekta. Če streže izvorno kodo, dobite index.html, ki kaže na /src/main.tsx, kar brskalniki ne morejo zagnati.

3. korak: preverite okoljske spremenljivke

Aplikacije na strani odjemalca pogosto ob gradnji preberejo nastavitve, kot sta naslov API ali javni ključ. Če spremenljivka na živi gradnji manjka, koda kot createClient(undefined, undefined) takoj vrže napako in stran postane bela.

Kaj je dobro vedeti:

• V Vite so v kodi brskalnika na voljo samo spremenljivke s predpono VITE_, branje z import.meta.env.VITE_IME. V Create React App je predpona REACT_APP_; v Next.js NEXT_PUBLIC_.
• Te vrednosti so vgrajene ob gradnji aplikacije. Dodajanje spremenljivke po gradnji nič ne spremeni, dokler ne ponovno zgradite in znova objavite.
• Predogled ali vaš lokalni računalnik morda ima datoteko .env, ki je produkcijska gradnja nima. Nastavite iste spremenljivke na gostitelju.
• Vse s temi predponami konča v javnem JavaScriptu. V to dajte samo javne vrednosti, nikoli skrivnih ključev.

Hiter test: v napaki v konzoli poiščite undefined ob imenu nastavitve ali vprašajte:

Objavljena aplikacija prikazuje prazno stran. Naštej vsako okoljsko spremenljivko, ki jo frontend bere, preveri, katere manjkajo ali so prazne v živi gradnji, in naredi, da aplikacija prikaže jasno sporočilo o napaki namesto prazne strani, kadar kaka manjka.

4. korak: odpravite zrušitev

Če konzola kaže običajno napako JavaScripta, se je koda zrušila med upodabljanjem. Tipični vzroki v aplikacijah, zgrajenih z AI:

• Podatki še niso naloženi. Komponenta bere user.name, preden je user prispel. Popravek je stanje nalaganja ali neobvezni dostop (user?.name).
• Prazni podatki. Nov račun nima zapisov, koda pa predpostavlja, da ima seznam vsaj en element.
• Nepričakovana oblika podatkov. API je vrnil objekt napake namesto seznama, ki ga koda pričakuje.
• Manjkajoč uvoz po preimenovanju ali premiku datoteke.
• Uporaba API-ja, ki obstaja samo v brskalniku, med upodabljanjem na strežniku, na primer window ali localStorage v strežniški komponenti Next.js.

Dajte AI celotno napako, stran in to, kako ste bili prijavljeni:

Stran Nadzorna plošča je za nove uporabnike prazna. Konzola: TypeError: Cannot read properties of undefined (reading 'map') v ProjectList.tsx:18. Deluje za moj račun, ki ima projekte. Popravi, da prazen račun prikaže »Še ni projektov«, in preveri nov račun v predogledu.

5. korak: dodajte mejo napake

V Reactu lahko ena komponenta, ki se zruši, odstrani celotno aplikacijo, zato majhna napaka povzroči popolnoma prazno stran. Meja napake (error boundary) je komponenta, ki ujame napake pri upodabljanju pod njo in namesto tega prikaže nadomestno vsebino.

Dodaj mejo napake okoli glavnih poti, ki prikaže »Nekaj je šlo narobe« z gumbom Ponovno naloži, in zabeleži napako v konzoli. Glava in navigacija naj ostaneta zunaj nje, da se še vedno prikažeta.

Ne odpravi napake, vendar obiskovalci vidijo sporočilo namesto prazne strani, vi pa vidite, kje se je pokvarilo.

6. korak: ni napak, a stran je prazna

Če je konzola čista in se skripte naložijo:

• Preverite zavihek Elementi. Ali je v <div id="root"> vsebina? Če da, se upodablja, vendar je nevidna: bel tekst na belem, opacity: 0, display: none ali element čez celoten zaslon, ki jo prekriva.
• Preverite usmerjevalnik. Če se nobena pot ne ujema s trenutnim URL-jem in ni poti »ni najdeno«, nekateri usmerjevalniki ne prikažejo ničesar. Dodajte zajemno pot, ki prikaže stran 404.
• Preverite točko pritrditve. Koda se mora pritrditi v element, ki obstaja. Če ima index.html id="app", koda pa išče root, se nič ne prikaže (in React običajno zabeleži napako).
• Preverite razširitev brskalnika. Poskusite v zasebnem oknu. Blokirniki oglasov občasno blokirajo skripte z imeni, kot sta analytics ali ads.

Prazna stran samo po osvežitvi strani?

Če domača stran deluje, osvežitev /dashboard pa prikaže prazno stran ali 404, strežnik ne ve, da mora za poti aplikacije poslati index.html. To je težava z rezervo usmerjanja, ki jo obravnava kako odpraviti napake 404 po objavi.

Pogoste napake

• Branje zadnje napake namesto prve. Prva rdeča vrstica je običajno vzrok.
• Nastavljanje okoljskih spremenljivk brez ponovne gradnje. Spremenljivke na strani odjemalca so določene ob gradnji.
• Testiranje samo z lastnim računom. Zrušitve praznih računov so ena najpogostejših vzrokov prazne strani.
• Predpostavka, da je objava uspela. Preverite dnevnik gradnje, preden odpravljate napake v kodi.
• Krivdo za vse pripisovati predpomnilniku brskalnika. Trdo osveževanje ga izključi v nekaj sekundah; če je stran še vedno prazna, je vzrok nekje drugje.

Prazne strani v Mythex

Če je Predogled prazen, najprej preverite, ali aplikacija teče (odprite Koda → terminal), nato pa prosite Mythex, naj zažene pravi strežnik, kliknite Osveži v orodni vrstici predogleda ali uporabite /fix. Za prazen objavljen URL dokumentacija predlaga, da počakate minuto in trdo osvežite, potrdite, da so okoljske spremenljivke in baza podatkov nastavljene pred objavo, ter preverite svoj obseg gostovanja. Ne pozabite, da je objavljena aplikacija posnetek: po popravku znova objavite. Če je spremembo povzročila sprememba, Vrni na to točko pri zadnjem dobrem odgovoru povrne projekt nazaj. Glejte Odpravljanje težav in Odpravljanje težav pri objavi v dokumentaciji ter naš splošni vodnik o odpravljanju napak v aplikaciji, zgrajeni z AI.

Kontrolni seznam za prazno stran

• Prebrana prva rdeča napaka v konzoli
• Preverjene datoteke .js/.css v zavihku Omrežje, ki vračajo 404 ali HTML
• Osnovna pot se ujema z mestom, kjer je aplikacija streženja
• Gradnja je končana in izhodna mapa gradnje je tista, ki je objavljena
• Vse okoljske spremenljivke na strani odjemalca nastavljene na živi gradnji, nato ponovna gradnja
• Zrušitev odpravljena, tudi za prazne in nove račune
• Meja napake nameščena, da bodo prihodnje zrušitve prikazale sporočilo
• Zajemna pot za neznane URL-je
• Preizkušeno po trdem osveževanju in v zasebnem oknu

Vprašanja