Cum repari o pagină albă în aplicația ta web

O pagină albă înseamnă aproape întotdeauna unul dintre două lucruri: JavaScript-ul aplicației s-a blocat înainte să deseneze ceva, sau JavaScript-ul nu s-a încărcat deloc. Deschide consola browserului (click dreapta → Inspect → Console), citește prima eroare roșie, apoi verifică tab-ul Network pentru fișiere care nu s-au încărcat. Cele mai multe cauze sunt o variabilă de mediu lipsă, o cale de bază greșită, un build care nu s-a terminat sau o eroare într-o singură componentă.

Acest ghid acoperă aplicațiile single-page construite cu React, Vue sau framework-uri similare (inclusiv aplicațiile făcute de constructoarele cu AI), unde paginile albe apar cel mai des.

De ce pagina este albă

O aplicație single-page (SPA) modernă trimite browserului un fișier HTML aproape gol, cam așa:

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

Apoi JavaScript construiește întreaga pagină în interiorul acelui div gol. Dacă scriptul nu se încarcă sau aruncă o eroare înainte să randeze, div-ul rămâne gol și vezi alb. Pagina nu este „stricată” vizibil; pur și simplu nu a fost desenată niciodată.

De aceea reparația începe mereu în uneltele de dezvoltator, nu în pagina în sine.

Pasul 1: Citește consola

Deschide uneltele de dezvoltator: click dreapta pe pagină și alege Inspect, sau apasă F12 (Cmd+Option+I pe Mac). Mergi la tab-ul Console și reîncarcă pagina.

Uitate-te la prima eroare roșie; cele de după sunt adesea efecte secundare. Ce spune ea indică cauza:

Copiază textul complet al erorii, inclusiv numele fișierului și numărul liniei. Dacă folosești un constructor cu AI, lipește-l direct în chat.

Pasul 2: Verifică dacă fișierele s-au încărcat

Deschide tab-ul Network, bifează Disable cache și reîncarcă. Uită-te la cererile pentru fișierele .js și .css.

• Status 404 pentru un fișier JavaScript: pagina cere un fișier care nu există pe server.
• Status 200, dar tipul este text/html: serverul a returnat o pagină (adesea chiar index.html, din cauza unei rezerve SPA) în loc de script. Aceeași cauză de bază: fișierul nu este acolo unde se așteaptă pagina.

Motive frecvente:

Cale de bază greșită. Dacă aplicația este servită dintr-un subfolder, de exemplu exemplu.ro/app/, dar a fost construită să încarce fișiere din /assets/..., fiecare cerere de script ratează. În Vite asta este opțiunea base din vite.config; în Create React App este câmpul homepage; în Next.js este basePath. Trebuie să se potrivească cu locul unde este servită efectiv aplicația.

index.html rămas vechi. Uneltele de build dau fișierelor nume cu un hash al conținutului, de exemplu index-a1b2c3.js. După un deploy nou, fișierul vechi dispare. Dacă un browser sau un CDN mai are în cache vechiul index.html, cere fișierul vechi și nu primește nimic. Un hard refresh (Cmd+Shift+R sau Ctrl+Shift+R) confirmă asta. Soluția pe termen lung este să servești index.html cu un header de cache scurt sau inexistent, în timp ce fișierele cu hash sunt păstrate mult timp în cache.

Build-ul nu s-a terminat sau nu a fost implementat. Dacă build-ul a eșuat, hostul poate servi un folder de rezultat vechi sau gol. Verifică jurnalul de build pentru erori.

Folderul greșit este publicat. Hostul trebuie să servească rezultatul build-ului (de obicei dist sau build), nu folderul sursă al proiectului. Dacă servești sursa, obții un index.html care indică spre /src/main.tsx, pe care browserele nu îl pot rula.

Pasul 3: Verifică variabilele de mediu

Aplicațiile front-end citesc adesea setări precum un URL de API sau o cheie publică la momentul build-ului. Dacă o variabilă lipsește în build-ul live, cod precum createClient(undefined, undefined) aruncă imediat o eroare, iar pagina devine albă.

Lucruri de știut:

• În Vite, doar variabilele cu prefixul VITE_ sunt disponibile în codul din browser, citite ca import.meta.env.VITE_NUME. În Create React App prefixul este REACT_APP_; în Next.js, NEXT_PUBLIC_.
• Aceste valori sunt fixate în aplicație la momentul build-ului. Adăugarea unei variabile după build nu face nimic până nu reconstruiești și nu redeployezi.
• Previzualizarea sau calculatorul local pot avea un fișier .env pe care build-ul de producție nu îl are. Setează aceleași variabile pe host.
• Orice cu aceste prefixe ajunge în JavaScript public. Pune acolo doar valori publice, niciodată chei secrete.

Un test rapid: caută în eroarea din consolă undefined lângă un nume de setare, sau cere:

Aplicația publicată afișează o pagină albă. Listează fiecare variabilă de mediu pe care o citește front-end-ul, verifică care lipsesc sau sunt goale în build-ul live și fă aplicația să afișeze un mesaj clar de eroare în loc de pagină albă când una lipsește.

Pasul 4: Repară blocajul

Dacă consola arată o eroare JavaScript obișnuită, codul s-a blocat în timpul randării. Cauze tipice în aplicațiile construite cu AI:

• Date neîncărcate încă. O componentă citește user.name înainte ca user să fi sosit. Soluția este o stare de încărcare sau optional chaining (user?.name).
• Date goale. Un cont nou nu are înregistrări, iar codul presupune că lista are cel puțin un element.
• Forma datelor neașteptată. Un API a returnat un obiect de eroare în loc de lista pe care o aștepta codul.
• Un import lipsă după ce un fișier a fost redenumit sau mutat.
• Folosirea unei API-uri disponibile doar în browser în timpul randării pe server, de exemplu window sau localStorage într-o componentă server Next.js.

Dă AI-ului eroarea completă, pagina și cu ce cont ești autentificat:

Pagina Dashboard este albă pentru utilizatorii noi. Consola: TypeError: Cannot read properties of undefined (reading 'map') la ProjectList.tsx:18. Funcționează pentru contul meu, care are proiecte. Repar-o astfel încât un cont gol să afișeze „Încă nu există proiecte” și verifică un cont nou în previzualizare.

Pasul 5: Adaugă un error boundary

În React, o singură componentă care se blochează poate demonta toată aplicația, de aceea o eroare mică produce o pagină complet albă. Un error boundary este o componentă care prinde erorile de randare de sub ea și afișează o variantă de rezervă.

Adaugă un error boundary în jurul rutelor principale, care afișează „Something went wrong” cu un buton Reload și înregistrează eroarea în consolă. Păstrează antetul și navigarea în afara lui, ca să se randeze în continuare.

Nu repară bug-ul, dar vizitatorii văd un mesaj în loc de ecran alb, iar tu vezi unde s-a stricat.

Pasul 6: Fără erori, dar tot alb

Dacă consola este curată și scripturile se încarcă:

• Verifică tab-ul Elements. Există conținut în <div id="root">? Dacă da, se randează, dar nu se vede: text alb pe fundal alb, opacity: 0, display: none sau un element pe tot ecranul care acoperă conținutul.
• Verifică routerul. Dacă nicio rută nu corespunde URL-ului curent și nu există o rută „not found”, unele routere nu randează nimic. Adaugă o rută catch-all care afișează o pagină 404.
• Verifică punctul de montare. Codul trebuie să se monteze într-un element care există. Dacă index.html are id="app", dar codul caută root, nu apare nimic (iar React de obicei înregistrează o eroare).
• Verifică o extensie de browser. Încearcă o fereastră privată. Ad blocker-ele blochează ocazional scripturi cu nume precum analytics sau ads.

Albă doar după refresh la o pagină?

Dacă pagina de start funcționează, dar refresh-ul la /dashboard arată o pagină albă sau un 404, serverul nu știe să trimită index.html pentru rutele aplicației. Aceasta este o problemă de rezervă a rutării, acoperită în cum repari erorile 404 după publicare.

Greșeli frecvente

• Citirea ultimei erori în loc de prima. Prima linie roșie este de obicei cauza.
• Setarea variabilelor de mediu fără rebuild. Variabilele de front-end sunt fixate la build.
• Testarea doar cu propriul cont. Erorile cu conturi goale sunt una dintre cele mai frecvente cauze ale paginii albe.
• Presupunerea că deploy-ul a reușit. Verifică jurnalul de build înainte să depanezi codul.
• Dat vina pe cache-ul browserului pentru orice. Un hard refresh îl exclude în câteva secunde; dacă pagina este tot albă, e altceva.

Pagini albe în Mythex

Dacă Previzualizarea este albă, verifică mai întâi că aplicația rulează (deschide Cod → terminal), apoi cere Mythex să pornească serverul corect, apasă Refresh în bara de instrumente a previzualizării sau folosește /fix. Pentru un URL publicat alb, documentația sugerează să aștepți un minut și să faci hard refresh, să confirmi că variabilele de mediu și baza de date au fost configurate înainte de publicare și să verifici limita de găzduire. Ține minte că o aplicație publicată este un instantaneu: după ce repari ceva, publică din nou. Dacă o schimbare a cauzat problema, Revert to this point de pe ultimul răspuns bun readuce proiectul înapoi. Vezi Depanare și Depanarea publicării în documentație și ghidul nostru general despre cum depanezi o aplicație construită cu AI.

Lista de verificare pentru pagina albă

• Am citit prima eroare roșie din Console
• Am verificat în Network fișierele .js/.css care dau 404 sau returnează HTML
• Calea de bază se potrivește cu locul unde este servită aplicația
• Build-ul s-a terminat, iar folderul de rezultat este cel publicat
• Toate variabilele de mediu ale front-end-ului sunt setate pe build-ul live, apoi reconstruit
• Eroarea este reparată, inclusiv pentru conturile goale și noi
• Error boundary pus, ca erorile viitoare să afișeze un mesaj
• Rută catch-all pentru URL-urile necunoscute
• Testat după hard refresh și într-o fereastră privată

Întrebări