Hogyan javítsa az üres, fehér oldalt a webappjában

Az üres fehér oldal majdnem mindig a két egyik dolgot jelenti: az app JavaScriptje összeomlott, mielőtt bármit kirajzolt volna, vagy a JavaScript egyáltalán nem töltődött be. Nyissa meg a böngésző konzolját (jobb klikk → Vizsgálat → Konzol), olvassa el az első piros hibát, majd nézze meg a Hálózat fület a sikertelenül betöltött fájlokért. A leggyakoribb okok: egy hiányzó környezeti változó, egy rossz base path, egy be nem fejezett build, vagy egy komponens összeomlása.

Ez az útmutató a React, Vue vagy hasonló keretrendszerekkel épített egyoldalas appokat (az AI-építők által készítetteket is) fedi le, ahol az üres oldal a leggyakoribb.

Miért fehér az oldal

Egy modern egyoldalas app (SPA) szinte üres HTML-fájlt küld a böngészőnek, nagyjából ilyet:

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

A JavaScript ezután az egész oldalt az üres div-en belül építi fel. Ha a szkript nem töltődik be, vagy a renderelés előtt hibát dob, a div üres marad, és fehéret lát. Az oldal nem „törött” látható módon; egyszerűen nem rajzolódott ki.

Ezért a javítás mindig a fejlesztői eszközökben kezdődik, nem magán az oldalon.

1. lépés: Olvassa el a konzolt

Nyissa meg a fejlesztői eszközöket: jobb klikk az oldalon, majd Vizsgálat, vagy F12 (Mac-en Cmd+Option+I). Menjen a Konzol fülre, és töltse újra az oldalt.

Az első piros hibát nézze meg; a későbbiek gyakran csak mellékhatások. Az, amit mond, mutatja az okot:

Másolja ki a teljes hibaszöveget, a fájlnévvel és a sorszámmal együtt. Ha AI-építőt használ, illessze be közvetlenül a chatbe.

2. lépés: Ellenőrizze, hogy a fájlok betöltődtek-e

Nyissa meg a Hálózat fület, pipálja be a Gyorsítótár letiltása opciót, és frissítsen. Nézze a .js és .css fájlok kéréseit.

• 404-es státusz egy JavaScript-fájlon: az oldal olyan fájlt kér, amely nincs a szerveren.
• 200-as státusz, de text/html típus: a szerver oldalt adott vissza a szkript helyett (gyakran magát az index.html-t, az SPA-fallback miatt). Ugyanaz az ok: a fájl nincs ott, ahol az oldal várja.

Gyakori okok:

Rossz base path. Ha az app egy almappából szolgálódik ki, például example.com/app/, de úgy lett buildelve, hogy a fájlokat /assets/...-ről töltse be, minden szkriptkérés célt téveszt. Vitében ez a vite.config base opciója; a Create React Appban a homepage mező; a Next.js-ben a basePath. Egyeznie kell azzal a címmel, ahol az app valójában fut.

Elavult index.html. A build eszközök a fájlokat tartalmi hash-sel nevezik el, például index-a1b2c3.js. Egy új telepítés után a régi fájl eltűnik. Ha a böngésző vagy a CDN még a régi index.html-t tárolja gyorsítótárban, a régi fájlt kéri, és semmit nem kap. A kemény frissítés (Cmd+Shift+R vagy Ctrl+Shift+R) ezt igazolja. A tartós megoldás, hogy az index.html rövid vagy nulla gyorsítótár-élettartamú fejlécet kapjon, míg a hashelt fájlok hosszú ideig gyorsítótárazhatók.

A build nem fejeződött be, vagy nem települt. Ha a build hibázott, a host lehet, hogy egy régi vagy üres kimeneti mappát szolgál ki. Ellenőrizze a build naplót hibákért.

Rossz mappa van közzétéve. A hostnak a build kimenetét kell szolgálnia (általában dist vagy build), nem a projekt forrásmappáját. A forrás kiszolgálása olyan index.html-t ad, amely a /src/main.tsx-re mutat, amelyet a böngésző nem tud futtatni.

3. lépés: Ellenőrizze a környezeti változókat

A front end appok gyakran build időben olvasnak olyan beállításokat, mint egy API URL vagy egy nyilvános kulcs. Ha egy változó hiányzik az élő buildből, az olyan kód, mint a createClient(undefined, undefined), azonnal hibát dob, és az oldal fehér lesz.

Érdemes tudni:

• Vitében csak a VITE_ előtaggal rendelkező változók érhetők el a böngészőben futó kódban, és import.meta.env.VITE_NAME-ként olvashatók. A Create React Appban ez REACT_APP_; a Next.js-ben NEXT_PUBLIC_.
• Ezek az értékek build időben vannak beégetve. Ha a build után ad hozzá változót, semmi nem történik, amíg újra nem buildel és nem telepít.
• A helyi gépen vagy az előnézetben lehet .env fájl, amelyet az éles build nem lát. Állítsa be ugyanezeket a változókat a hoston.
• Minden ilyen előtagú érték a nyilvános JavaScriptbe kerül. Csak nyilvános értékeket tegyen ide, soha titkos kulcsot.

Gyors teszt: keressen a konzolhibában undefined-ot egy beállítás neve közelében, vagy kérdezze meg:

Az élesített app üres oldalt mutat. Sorolja fel az összes környezeti változót, amelyet a front end olvas, ellenőrizze, melyik hiányzik vagy üres az élő buildben, és tegye úgy, hogy az app egyértelmű hibaüzenetet mutasson üres oldal helyett, ha egy hiányzik.

4. lépés: Javítsa az összeomlást

Ha a konzol normál JavaScript-hibát mutat, a kód renderelés közben omlott össze. Tipikus okok AI-val épített appokban:

• Az adatok még nincsenek betöltve. Egy komponens a user.name-et olvassa, mielőtt a user megérkezett. A javítás egy betöltési állapot, vagy optional chaining (user?.name).
• Üres adatok. Egy új fiókban nincs rekord, a kód pedig feltételezi, hogy a lista legalább egy elemet tartalmaz.
• Váratlan adatforma. Egy API hibaobjektumot adott a várt lista helyett.
• Hiányzó import, miután egy fájlt átneveztek vagy áthelyeztek.
• Csak böngészőben elérhető API használata szerveroldali renderelés közben, például a window vagy a localStorage egy Next.js szerverkomponensben.

Adja az AI-nak a teljes hibát, az oldalt, és azt, hogy mivel volt bejelentkezve:

Az Irányítópult oldal üres az új felhasználóknak. Konzol: TypeError: Cannot read properties of undefined (reading 'map') a ProjectList.tsx:18 helyen. A saját fiókomnak működik, mert vannak projektjei. Javítsa úgy, hogy egy üres fiók „Még nincs projekt” üzenetet mutasson, és ellenőrizze egy új fiókon az előnézetben.

5. lépés: Adjon hozzá hibahatárt

Reactben egyetlen összeomló komponens lecsatolhatja az egész appot, ezért okoz egy kis hiba teljesen üres oldalt. A hibahatár (error boundary) olyan komponens, amely elkapja a renderelési hibákat a alatta lévő részben, és helyette tartalék nézetet mutat.

Adjon hibahatárt a fő útvonalak köré, amely „Valami hiba történt” üzenetet mutat egy Újratöltés gombbal, és a hibát a konzolba naplózza. A fejléc és a navigáció maradjon a határon kívül, hogy továbbra is megjelenjenek.

Ez nem javítja a hibát, de a látogatók üzenetet látnak az üres képernyő helyett, Ön pedig látja, hol tört el.

6. lépés: Nincs hiba, mégis üres

Ha a konzol tiszta, és a szkriptek betöltődnek:

• Nézze meg az Elemek fület. Van-e tartalom a <div id="root"> belsejében? Ha igen, akkor renderel, de láthatatlan: fehér szöveg fehér háttéren, opacity: 0, display: none, vagy egy teljes képernyős elem fedi.
• Nézze meg a routert. Ha egyetlen útvonal sem egyezik az aktuális URL-lel, és nincs „nem található” útvonal, egyes routerek semmit nem renderelnek. Adjon hozzá egy catch-all útvonalat, amely 404-oldalt mutat.
• Nézze meg a csatolási pontot. A kódnak egy létező elembe kell csatolódnia. Ha az index.html-ben id="app" van, a kód pedig root-ot keres, semmi nem jelenik meg (és a React általában logol egy hibát).
• Nézze meg a böngészőbővítményeket. Próbálja magán ablakban. A hirdetésblokkolók néha letiltanak olyan szkripteket, amelyek nevében analytics vagy ads szerepel.

Csak egy oldal frissítése után üres?

Ha a főoldal működik, de a /dashboard frissítésekor üres oldal vagy 404 jelenik meg, a szerver nem tudja, hogy az app útvonalaira az index.html-t kell küldenie. Ez egy útválasztási fallback probléma, amelyet a 404-es hibák javítása telepítés után útmutató fed le.

Gyakori hibák

• Az utolsó hibát olvasni az első helyett. Az első piros sor általában az ok.
• Környezeti változókat beállítani újraépítés nélkül. A front end változók build időben rögzülnek.
• Csak a saját fiókkal tesztelni. Az üres fiókon történő összeomlás az egyik leggyakoribb üres oldal-ok.
• Feltételezni, hogy a telepítés sikerült. Ellenőrizze a build naplót, mielőtt a kódot hibakeresi.
• Mindent a böngésző gyorsítótárára fogni. A kemény frissítés másodpercek alatt kizárja ezt; ha az oldal még mindig üres, valami más az ok.

Üres oldalak a Mythexben

Ha az Előnézet üres, először ellenőrizze, hogy az app fut-e (nyissa meg a Kód → terminál részt), majd kérje meg a Mythexet, hogy indítsa el a megfelelő szervert, kattintson az Frissítés gombra az előnézet eszköztárában, vagy használja a /fix parancsot. Egy üres közzétett URL esetén a dokumentáció azt javasolja, hogy várjon egy percet és frissítsen erőteljesen, ellenőrizze, hogy a környezeti változók és az adatbázis be lettek állítva a közzététel előtt, és nézze meg a tárhely-keretét. Ne feledje, hogy a közzétett app pillanatkép: egy javítás után újra publikáljon. Ha egy változtatás okozta, a Visszaállítás erre a pontra az utolsó jó válasznál visszaállítja a projektet. Lásd: Hibaelhárítás és Publikálási hibaelhárítás a dokumentációban, és az általános útmutatónkat: AI-val épített app hibakeresése.

Üres oldal ellenőrzőlista

• Elolvastam az első piros hibát a Konzolban
• Ellenőriztem a Hálózat fület a 404-et adó vagy HTML-t visszaadó .js/.css fájlokért
• A base path egyezik azzal a címmel, ahol az app szolgálódik ki
• A build befejeződött, és a build kimeneti mappa az, amely közzé van téve
• Minden front end környezeti változó beállítva az élő buildre, majd újraépítve
• Az összeomlás javítva, az üres és új fiókokra is
• Hibahatár van, így a jövőbeli összeomlások üzenetet mutatnak
• Catch-all útvonal az ismeretlen URL-ekhez
• Tesztelve kemény frissítés után és magán ablakban

Kérdések