Ako opraviť prázdnu bielu stránku vo webovej aplikácii

Prázdna biela stránka takmer vždy znamená jednu z dvoch vecí: JavaScript aplikácie spadol skôr, než niečo vykreslil, alebo sa JavaScript vôbec nenačítal. Otvorte konzolu prehliadača (pravý klik → Preskúmať → Konzola), prečítajte si prvú červenú chybu a potom v karte Sieť skontrolujte súbory, ktoré sa nenačítali. Väčšinou ide o chýbajúcu premennú prostredia, zlú základnú cestu, build, ktorý sa nedokončil, alebo pád v jednom komponente.

Tento návod pokrýva jednostránkové aplikácie (SPA) postavené na Reacte, Vue alebo podobných frameworkoch (vrátane aplikácií vytvorených nástrojmi s AI), kde sú prázdne stránky najčastejšie.

Prečo je stránka biela

Moderná SPA pošle prehliadaču takmer prázdny HTML súbor, zhruba takto:

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

JavaScript potom vytvorí celú stránku vo vnútri toho prázdneho div. Ak sa skript nenačíta alebo pred vykreslením hodí chybu, div zostane prázdny a vy vidíte bielu. Stránka nie je „rozbitá“ viditeľným spôsobom; jednoducho sa nikdy nevykreslila.

Preto oprava vždy začína vo vývojárskych nástrojoch, nie na samotnej stránke.

Krok 1: Prečítajte konzolu

Otvorte vývojárske nástroje: pravý klik na stránku a Preskúmať, alebo F12 (Cmd+Option+I na Macu). Prejdite na kartu Konzola a stránku znovu načítajte.

Pozrite sa na prvú červenú chybu; neskoršie sú často len vedľajšie účinky. To, čo hovorí, ukáže na príčinu:

Skopírujte celý text chyby vrátane názvu súboru a čísla riadku. Ak používate nástroj na tvorbu s AI, vložte ho priamo do chatu.

Krok 2: Skontrolujte, či sa súbory načítali

Otvorte kartu Sieť, zaškrtnite Zakázať cache a načítajte stránku znovu. Pozrite sa na požiadavky na súbory .js a .css.

• Stavový kód 404 pri JavaScriptovom súbore: stránka žiada súbor, ktorý na serveri nie je.
• Stav 200, ale typ text/html: server vrátil stránku (často samotný index.html, kvôli záložnému pravidlu SPA) namiesto skriptu. Koreňová príčina je rovnaká: súbor nie je tam, kde ho stránka očakáva.

Bežné dôvody:

Zlá základná cesta. Ak je aplikácia obsluhovaná z podpriečinka, napríklad example.com/app/, ale bola zostavená tak, aby načítavala súbory z /assets/..., každá požiadavka na skript minie cieľ. Vo Vite je to možnosť base v vite.config; v Create React App pole homepage; v Next.js basePath. Musí zodpovedať tomu, kde je aplikácia skutočne obsluhovaná.

Zastaraný index.html. Nástroje na zostavenie dávajú súborom názvy s hashom obsahu, napríklad index-a1b2c3.js. Po novom nasadení starý súbor zmizne. Ak prehliadač alebo CDN má stále uložený starý index.html, pýta sa na starý súbor a nedostane nič. Tvrdé obnovenie (Cmd+Shift+R alebo Ctrl+Shift+R) to potvrdí. Dlhodobá oprava je obsluhovať index.html s krátkou alebo žiadnou cache hlavičkou, zatiaľ čo súbory s hashom môžu byť uložené dlho.

Build sa nedokončil alebo nebol nasadený. Ak build zlyhal, hosting môže obsluhovať starý alebo prázdny výstupný priečinok. Skontrolujte log buildu, či nie sú chyby.

Publikuje sa nesprávny priečinok. Hosting musí obsluhovať výstup buildu (zvyčajne dist alebo build), nie zdrojový priečinok projektu. Zdrojový priečinok vám dá index.html, ktorý ukazuje na /src/main.tsx, a ten prehliadače nedokážu spustiť.

Krok 3: Skontrolujte premenné prostredia

Frontendové aplikácie často načítavajú nastavenia ako URL API alebo verejný kľúč v čase buildu. Ak premenná na živom builde chýba, kód ako createClient(undefined, undefined) okamžite spadne a stránka zbelie.

Čo treba vedieť:

• Vo Vite sú v kóde prehliadača dostupné len premenné s predponou VITE_, čítané ako import.meta.env.VITE_NAME. V Create React App je to REACT_APP_; v Next.js NEXT_PUBLIC_.
• Tieto hodnoty sa zapečú pri zostavení aplikácie. Pridanie premennej po builde nič nezmení, kým znovu nezostavíte a nenasadíte.
• Lokálny počítač alebo náhľad môže mať súbor .env, ktorý produkčný build nemá. Nastavte rovnaké premenné na hostingu.
• Všetko s týmito predponami sa dostane do verejného JavaScriptu. Dávajte tam len verejné hodnoty, nikdy tajné kľúče.

Rýchly test: v chybe v konzole hľadajte undefined pri názve nastavenia, alebo sa opýtajte:

Publikovaná aplikácia zobrazuje prázdnu stránku. Vypíš každú premennú prostredia, ktorú frontend číta, skontroluj, ktoré chýbajú alebo sú prázdne v živom builde, a spravi tak, aby aplikácia pri chýbajúcej premennej zobrazila jasnú chybovú správu namiesto prázdnej stránky.

Krok 4: Opravte pád

Ak konzola ukazuje bežnú chybu JavaScriptu, kód spadol pri vykresľovaní. Typické príčiny v aplikáciách vytvorených s AI:

• Dáta ešte nie sú načítané. Komponent číta user.name, kým user ešte nedorazil. Oprava je stav načítavania alebo volanie s volitelným reťazcom (user?.name).
• Prázdne dáta. Nový účet nemá záznamy a kód predpokladá, že zoznam má aspoň jednu položku.
• Neočakávaný tvar dát. API vrátilo chybový objekt namiesto zoznamu, ktorý kód očakával.
• Chýbajúci import po tom, čo bol súbor premenovaný alebo presunutý.
• Použitie API dostupného len v prehliadači pri vykresľovaní na strane servera, napríklad window alebo localStorage v serverovom komponente Next.js.

Dajte AI celú chybu, stránku a to, kým ste boli prihlásení:

Stránka Dashboard je pre nových používateľov prázdna. Konzola: TypeError: Cannot read properties of undefined (reading 'map') v ProjectList.tsx:18. Funguje to pre môj účet, ktorý má projekty. Oprav to tak, aby prázdny účet zobrazil „Zatiaľ žiadne projekty“, a over nový účet v náhľade.

Krok 5: Pridajte error boundary

V Reacte môže jeden pádový komponent odpojiť celú aplikáciu, preto malá chyba vytvorí úplne prázdnu stránku. Error boundary je komponent, ktorý zachytáva chyby vykresľovania pod sebou a namiesto nich zobrazí záložný obsah.

Pridaj error boundary okolo hlavných trás, ktorý zobrazí „Niečo sa pokazilo“ s tlačidlom Znovu načítať a zapíše chybu do konzoly. Hlavičku a navigáciu nechaj mimo neho, aby sa stále vykresľovali.

Nespraví to chybu opravenou, ale návštevníci uvidia správu namiesto prázdnej obrazovky a vy uvidíte, kde to zlyhalo.

Krok 6: Žiadne chyby, no stále prázdne

Ak je konzola čistá a skripty sa načítavajú:

• Skontrolujte kartu Elements. Je niečo vnútri <div id="root">? Ak áno, vykresľuje sa, ale je neviditeľné: biely text na bielom, opacity: 0, display: none alebo element cez celú obrazovku, ktorý ho prekrýva.
• Skontrolujte smerovanie. Ak sa nezhoduje žiadna trasa s aktuálnou URL a nie je tam trasa „nenájdené“, niektoré routery nevykreslia nič. Pridajte zachytávaciu trasu, ktorá zobrazí stránku 404.
• Skontrolujte prípojný bod. Kód sa musí pripojiť do prvku, ktorý existuje. Ak index.html má id="app" a kód hľadá root, nič sa nezobrazí (a React zvyčajne zaloguje chybu).
• Skontrolujte rozšírenie prehliadača. Skúste súkromné okno. Blokovače reklám občas blokujú skripty s názvami ako analytics alebo ads.

Prázdna len po obnovení stránky?

Ak domovská stránka funguje, ale obnovenie /dashboard zobrazí prázdnu stránku alebo 404, server nevie, že má pre trasy aplikácie poslať index.html. To je problém záložného smerovania, ktorý rieši ako opraviť 404 chyby po nasadení.

Časté chyby

• Čítanie poslednej chyby namiesto prvej. Prvý červený riadok je zvyčajne príčina.
• Nastavenie premenných prostredia bez nového buildu. Premenné frontendu sú pevne zapísané v čase buildu.
• Testovanie len vlastným účtom. Pády pri prázdnych účtoch sú jednou z najčastejších príčin prázdnych stránok.
• Predpoklad, že nasadenie prebehlo. Pred ladením kódu skontrolujte log buildu.
• Vinenie cache prehliadača za všetko. Tvrdé obnovenie to vylúči za pár sekúnd; ak je stránka stále prázdna, je to niečo iné.

Prázdne stránky v Mythex

Ak je náhľad prázdny, najprv overte, že aplikácia beží (otvorte Kód → terminál), potom požiadajte Mythex, aby spustil správny server, kliknite na Obnoviť na paneli náhľadu alebo použite /fix. Pri prázdnej publikovanej URL dokumentácia odporúča počkať minútu a tvrdo obnoviť stránku, overiť, že premenné prostredia a databáza boli nastavené pred publikovaním, a skontrolovať limit hostingu. Pamätajte, že publikovaná aplikácia je snímka: po oprave znovu publikujte. Ak zmenu spôsobila nejaká úprava, Vrátiť k tomuto bodu pri poslednej dobrej odpovedi vráti projekt späť. Pozri Riešenie problémov a Riešenie problémov pri publikovaní v dokumentácii a náš všeobecný návod ako ladiť aplikáciu vytvorenú s AI.

Kontrolný zoznam prázdnej stránky

• Prečítaná prvá červená chyba v konzole
• Skontrolovaná karta Sieť: .js/.css súbory, ktoré zlyhávajú s 404 alebo vracajú HTML
• Základná cesta zodpovedá tomu, kde je aplikácia obsluhovaná
• Build sa dokončil a publikovaný je výstupný priečinok buildu
• Všetky premenné prostredia frontendu nastavené na živom builde, potom nový build
• Pád opravený, vrátane prázdnych a nových účtov
• Error boundary na mieste, aby budúce pády zobrazili správu
• Zachytávacia trasa pre neznáme URL
• Testované po tvrdom obnovení a v súkromnom okne

Otázky