Jak opravit prázdnou bílou stránku ve webové aplikaci

Prázdná bílá stránka téměř vždy znamená jednu ze dvou věcí: JavaScript aplikace spadl dřív, než něco vykreslil, nebo se JavaScript vůbec nenačetl. Otevřete konzoli prohlížeče (pravý klik → Prozkoumat → Konzole), přečtěte první červenou chybu a pak zkontrolujte záložku Síť, zda se nenačetly některé soubory. Nejčastější příčiny jsou chybějící proměnná prostředí, špatná základní cesta, sestavení, které nedoběhlo, nebo pád jedné komponenty.

Tento návod pokrývá jednostránkové aplikace postavené na Reactu, Vue nebo podobných frameworcích (včetně aplikací vytvořených nástroji s AI), kde se prázdné stránky objevují nejčastěji.

Proč je stránka bílá

Moderní jednostránková aplikace (SPA) pošle prohlížeči téměř prázdný HTML soubor, zhruba takto:

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

JavaScript pak celou stránku sestaví uvnitř toho prázdného div. Pokud se skript nenačte, nebo vyhodí chybu dřív, než vykreslí, div zůstane prázdný a vy vidíte bílou. Stránka není „rozbitá“ viditelným způsobem; jen se nikdy nevykreslila.

Proto oprava vždy začíná ve vývojářských nástrojích, ne na samotné stránce.

Krok 1: Čtěte konzoli

Otevřete vývojářské nástroje: pravým klikem na stránku zvolte Prozkoumat, nebo stiskněte F12 (Cmd+Option+I na Macu). Přejděte na záložku Konzole a stránku obnovte.

Podívejte se na první červenou chybu; pozdější jsou často jen vedlejší efekty. To, co říká, ukazuje příčinu:

Zkopírujte celý text chyby včetně názvu souboru a čísla řádku. Pokud používáte nástroj s AI, vložte ho rovnou do chatu.

Krok 2: Zkontrolujte, zda se soubory načetly

Otevřete záložku Síť, zaškrtněte Zakázat cache a obnovte stránku. Podívejte se na požadavky na soubory .js a .css.

• Stav 404 u JavaScriptového souboru: stránka žádá soubor, který na serveru není.
• Stav 200, ale typ text/html: server vrátil stránku (často samotný index.html kvůli záložnímu SPA pravidlu) místo skriptu. Stejná hlavní příčina: soubor není tam, kde ho stránka čeká.

Běžné důvody:

Špatná základní cesta. Pokud je aplikace servírována z podsložky, například priklad.cz/app/, ale byla sestavena tak, aby načítala soubory z /assets/..., každý požadavek na skript mine. Ve Vite je to volba base v vite.config; v Create React App pole homepage; v Next.js basePath. Musí odpovídat místu, kde je aplikace skutečně servírována.

Zastaralý index.html. Nástroje pro sestavení dávají souborům názvy s hashem obsahu, například index-a1b2c3.js. Po novém nasazení starý soubor zmizí. Pokud prohlížeč nebo CDN stále drží starý index.html v cache, požádá o starý soubor a nedostane nic. Tvrdé obnovení (Cmd+Shift+R nebo Ctrl+Shift+R) to potvrdí. Dlouhodobá oprava je posílat index.html s krátkou nebo žádnou cache, zatímco soubory s hashem se mohou cachovat dlouho.

Sestavení nedoběhlo nebo se nenasadilo. Pokud sestavení selhalo, hosting může servírovat starou nebo prázdnou výstupní složku. Zkontrolujte log sestavení na chyby.

Publikována je špatná složka. Hosting musí servírovat výstup sestavení (obvykle dist nebo build), ne zdrojovou složku projektu. Zdrojová složka vám dá index.html, který ukazuje na /src/main.tsx, což prohlížeče nemohou spustit.

Krok 3: Zkontrolujte proměnné prostředí

Frontendové aplikace často čtou nastavení jako URL API nebo veřejný klíč v době sestavení. Pokud na živém sestavení chybí proměnná, kód jako createClient(undefined, undefined) okamžitě spadne a stránka zbělá.

Na co myslet:

• Ve Vite jsou v kódu prohlížeče dostupné jen proměnné s předponou VITE_, čtou se jako import.meta.env.VITE_NAME. V Create React App je to REACT_APP_; v Next.js NEXT_PUBLIC_.
• Tyto hodnoty se zapékají při sestavení. Přidání proměnné po sestavení nic nezmění, dokud znovu nesestavíte a nenasadíte.
• Místní počítač nebo náhled může mít soubor .env, který produkční sestavení nemá. Nastavte stejné proměnné na hostingu.
• Cokoli s těmito předponami skončí ve veřejném JavaScriptu. Dávejte tam jen veřejné hodnoty, nikdy tajné klíče.

Rychlý test: v chybě z konzole hledejte undefined u názvu nastavení, nebo se zeptejte:

Publikovaná aplikace ukazuje prázdnou stránku. Vypiš každou proměnnou prostředí, kterou frontend čte, zkontroluj, které v živém sestavení chybí nebo jsou prázdné, a udělej tak, aby aplikace místo prázdné stránky ukázala jasnou chybovou zprávu, když nějaká chybí.

Krok 4: Opravte pád

Pokud konzole ukazuje běžnou JavaScriptovou chybu, kód spadl během vykreslování. Typické příčiny u aplikací vytvořených s AI:

• Data ještě nejsou načtena. Komponenta čte user.name, dokud user ještě nedorazil. Oprava je stav načítání nebo volitelné řetězení (user?.name).
• Prázdná data. Nový účet nemá žádné záznamy a kód předpokládá, že seznam má alespoň jednu položku.
• Nečekaný tvar dat. API vrátilo chybový objekt místo seznamu, který kód očekával.
• Chybějící import po přejmenování nebo přesunutí souboru.
• Použití API dostupného jen v prohlížeči během renderování na serveru, například window nebo localStorage v serverové komponentě Next.js.

Dejte AI celou chybu, stránku a to, pod jakým účtem jste byli přihlášeni:

Stránka Dashboard je pro nové uživatele prázdná. Konzole: TypeError: Cannot read properties of undefined (reading 'map') na ProjectList.tsx:18. Funguje pro můj účet, který má projekty. Oprav to tak, aby prázdný účet ukázal „Zatím žádné projekty“, a v náhledu zkontroluj nový účet.

Krok 5: Přidejte error boundary

V Reactu může jedna padající komponenta odpojit celou aplikaci, proto malá chyba vytvoří úplně prázdnou stránku. Error boundary je komponenta, která zachytí chyby vykreslování pod ní a místo toho zobrazí záložní obsah.

Přidej error boundary kolem hlavních tras, který zobrazí „Něco se pokazilo“ s tlačítkem Znovu načíst a zapíše chybu do konzole. Hlavičku a navigaci nech mimo něj, aby se dál vykreslovaly.

Neopraví to chybu, ale návštěvníci uvidí zprávu místo prázdné obrazovky a vy uvidíte, kde to spadlo.

Krok 6: Žádné chyby, ale pořád prázdno

Pokud je konzole čistá a skripty se načítají:

• Zkontrolujte záložku Elements. Je něco uvnitř <div id="root">? Pokud ano, vykresluje se, ale není to vidět: bílý text na bílém, opacity: 0, display: none, nebo přes celou obrazovku přetéká prvek, který to překrývá.
• Zkontrolujte směrovač. Pokud žádná trasa neodpovídá aktuální URL a neexistuje trasa „nenalezeno“, některé směrovače nevykreslí nic. Přidejte zachytávací trasu, která zobrazí stránku 404.
• Zkontrolujte místo připojení. Kód se musí připojit k prvku, který existuje. Pokud index.html má id="app" a kód hledá root, nic se nezobrazí (a React obvykle zapíše chybu).
• Zkontrolujte rozšíření prohlížeče. Zkuste anonymní okno. Blokovače reklam občas zablokují skripty s názvy jako analytics nebo ads.

Prázdno jen po obnovení stránky?

Pokud domovská stránka funguje, ale obnovení /dashboard ukazuje prázdnou stránku nebo 404, server neví, že má pro aplikační trasy posílat index.html. To je problém záložního směrování, který pokrývá jak opravit chyby 404 po nasazení.

Časté chyby

• Číst poslední chybu místo první. První červený řádek je obvykle příčina.
• Nastavit proměnné prostředí bez nového sestavení. Proměnné frontendu jsou pevně dané v době sestavení.
• Testovat jen se svým účtem. Pády u prázdných účtů patří k nejčastějším příčinám prázdných stránek.
• Předpokládat, že nasazení proběhlo. Před laděním kódu zkontrolujte log sestavení.
• Svalovat všechno na cache prohlížeče. Tvrdé obnovení to vyloučí za pár sekund; pokud je stránka pořád prázdná, je to něco jiného.

Prázdné stránky v Mythex

Pokud je náhled prázdný, nejdřív zkontrolujte, zda aplikace běží (otevřete Kód → terminál), a pak požádejte Mythex, aby spustil správný server, klikněte na Obnovit v nástrojové liště náhledu, nebo použijte /fix. U prázdné publikované URL dokumentace doporučuje počkat minutu a udělat tvrdé obnovení, ověřit, že proměnné prostředí a databáze byly nastaveny před publikací, a zkontrolovat svůj limit hostingu. Pamatujte, že publikovaná aplikace je snímek: po opravě publikujte znovu. Pokud změnu způsobila úprava, Revert to this point u poslední funkční odpovědi vrátí projekt zpět. Viz Řešení problémů a Řešení problémů s publikací v dokumentaci a náš obecný návod jak ladit aplikaci postavenou s AI.

Kontrolní seznam prázdné stránky

• Přečtena první červená chyba v konzoli
• Zkontrolována záložka Síť na soubory .js/.css, které vracejí 404 nebo HTML
• Základní cesta odpovídá místu, kde je aplikace servírována
• Sestavení doběhlo a publikována je výstupní složka sestavení
• Všechny proměnné prostředí frontendu nastaveny na živém sestavení, pak sestaveno znovu
• Pád opraven, včetně prázdných a nových účtů
• Error boundary na místě, aby budoucí pády ukázaly zprávu
• Zachytávací trasa pro neznámé URL
• Otestováno po tvrdém obnovení a v anonymním okně

Otázky