Si të rregulloni një faqe të bardhë bosh në aplikacionin tuaj web

Një faqe e bardhë bosh zakonisht do të thotë një nga dy gjërat: JavaScript i aplikacionit u rrëzua përpara se të vizatonte diçka, ose JavaScript nuk u ngarkua fare. Hapni konsolën e shfletuesit (klikoni me të djathtën → Inspect → Console) dhe lexoni gabimin e parë të kuq, pastaj kontrolloni skedën Network për skedarët që nuk u ngarkuan. Shumica e shkaqeve janë një variabël mjedisi që mungon, një rrugë bazë e gabuar, një ndërtim që nuk përfundoi, ose një rrëzim në një komponent.

Ky udhëzues mbulon aplikacionet me një faqe (SPA) të ndërtuara me React, Vue ose korniza të ngjashme (përfshirë aplikacionet e bëra nga ndërtuesit me AI), ku faqet e bardha boshe janë më të zakonshme.

Pse faqja është e bardhë

Një aplikacion modern me një faqe (SPA) i dërgon shfletuesit një skedar HTML pothuajse bosh, afërsisht kështu:

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

JavaScript pastaj e ndërton të gjithë faqen brenda atij div bosh. Nëse skripti nuk ngarkohet, ose hedh një gabim përpara se të vizatojë, div mbetet bosh dhe shihni të bardhë. Faqja nuk është "e prishur" në një mënyrë që duket; thjesht nuk u vizatua kurrë.

Prandaj rregullimi fillon gjithmonë te mjetet e zhvilluesit, jo në vetë faqe.

Hapi 1: Lexoni konsolën

Hapni mjetet e zhvilluesit: klikoni me të djathtën në faqe dhe zgjidhni Inspect, ose shtypni F12 (Cmd+Option+I në Mac). Shkoni te skeda Console dhe rifreskoni faqen.

Shikoni gabimin e parë të kuq; ato të mëvonshmet shpesh janë efekte anësore. Ajo që thotë tregon shkakun:

Kopjoni tekstin e plotë të gabimit, përfshirë emrin e skedarit dhe numrin e rreshtit. Nëse përdorni një ndërtues me AI, ngjiteni direkt në chat.

Hapi 2: Kontrolloni që skedarët u ngarkuan

Hapni skedën Network, shenjoni Disable cache, dhe rifreskoni. Shikoni kërkesat për skedarët .js dhe .css.

• Status 404 te një skedar JavaScript: faqja kërkon një skedar që nuk është në server.
• Status 200, por lloji është text/html: serveri ktheu një faqe (shpesh vetë index.html, për shkak të një rezerve SPA) në vend të skriptit. Shkaku i njëjtë rrënjë: skedari nuk është aty ku pret faqja.

Arsye të zakonshme:

Rruga bazë e gabuar. Nëse aplikacioni shërbehet nga një nën-dosje, si example.com/app/, por është ndërtuar për të ngarkuar skedarët nga /assets/..., çdo kërkesë për skript humbet. Në Vite kjo është opsioni base në vite.config; në Create React App është fusha homepage; në Next.js është basePath. Duhet të përputhet me vendin ku shërbehet aplikacioni.

index.html i vjetër. Mjetet e ndërtimit i japin skedarëve emra me hash përmbajtjeje, si index-a1b2c3.js. Pas një publikimi të ri, skedari i vjetër zhduket. Nëse një shfletues ose CDN ka ende të ruajtur index.html të vjetër, ai kërkon skedarin e vjetër dhe nuk merr asgjë. Një rifreskim i fortë (Cmd+Shift+R ose Ctrl+Shift+R) e konfirmon këtë. Zgjidhja afatgjatë është të shërbeni index.html me një header me kohë të shkurtër ose pa cache, ndërsa skedarët me hash ruhen për kohë të gjatë.

Ndërtimi nuk u krye ose nuk u publikua. Nëse ndërtimi dështoi, hosti mund të shërbejë një dosje daljeje të vjetër ose bosh. Kontrolloni regjistrin e ndërtimit për gabime.

Dosja e gabuar është publikuar. Hosti duhet të shërbejë daljen e ndërtimit (zakonisht dist ose build), jo dosjen burim të projektit. Shërbimi i burimit ju jep një index.html që tregon te /src/main.tsx, që shfletuesit nuk mund ta ekzekutojnë.

Hapi 3: Kontrolloni variablat e mjedisit

Aplikacionet e front end-it zakonisht lexojnë cilësime si një URL API ose një çelës publik në kohën e ndërtimit. Nëse një variabël mungon në ndërtimin aktiv, kod si createClient(undefined, undefined) hedh gabim menjëherë, dhe faqja bëhet e bardhë.

Gjëra për t'i ditur:

• Në Vite, vetëm variablat me prefiksin VITE_ janë të disponueshme në kodin e shfletuesit, të lexuara si import.meta.env.VITE_NAME. Në Create React App është REACT_APP_; në Next.js, NEXT_PUBLIC_.
• Këto vlera futen në kohën e ndërtimit. Shtimi i një variabli pas ndërtimit nuk bën asgjë derisa të ndërtoni dhe publikoni përsëri.
• Vendi lokal ose pamja paraprake mund të ketë një skedar .env që ndërtimi i prodhimit nuk e ka. Vendosni të njëjtat variabla në host.
• Çdo gjë me këto prefikse përfundon në JavaScript publik. Vendosni aty vetëm vlera publike, kurrë çelësa sekretë.

Një test i shpejtë: kërkoni në gabimin e konsolës undefined pranë emrit të një cilësimi, ose pyesni:

Aplikacioni i publikuar shfaq një faqe bosh. Listo çdo variabël mjedisi që lexon front end-i, kontrollo cilat mungojnë ose janë bosh në ndërtimin aktiv, dhe bëje aplikacionin të shfaqë një gabim të qartë në vend të një faqeje boshe kur mungon një.

Hapi 4: Rregulloni rrëzimin

Nëse konsola shfaq një gabim normal JavaScript, kodi u rrëzua gjatë vizatimit. Shkaqe tipike në aplikacionet e ndërtuara me AI:

• Të dhënat nuk janë ngarkuar ende. Një komponent lexon user.name përpara se user të arrijë. Zgjidhja është një gjendje ngarkimi, ose zinxhiri opsional (user?.name).
• Të dhëna bosh. Një llogari e re nuk ka regjistrime, dhe kodi supozon se lista ka të paktën një element.
• Formë e papritur e të dhënave. Një API ktheu një objekt gabimi në vend të listës që priste kodi.
• Një import që mungon pasi një skedar u riemërua ose u zhvendos.
• Përdorimi i një API-je që ekziston vetëm në shfletues gjatë render-it në server, si window ose localStorage në një komponent server të Next.js.

Jepini AI-së gabimin e plotë, faqen dhe me cilën llogari ishit kyçur:

Faqja e Dashboard është bosh për përdoruesit e rinj. Konsola: TypeError: Cannot read properties of undefined (reading 'map') te ProjectList.tsx:18. Funksionon për llogarinë time, që ka projekte. Rregullo që një llogari bosh të shfaqë "Nuk ka projekte ende", dhe kontrollo një llogari të re në pamjen paraprake.

Hapi 5: Shtoni një error boundary

Në React, një komponent që rrëzohet mund ta çmontojë të gjithë aplikacionin, prandaj një gabim i vogël prodhon një faqe krejt të bardhë. Një error boundary është një komponent që kap gabimet e vizatimit poshtë tij dhe shfaq një rezervë në vend të tyre.

Shto një error boundary rreth rrugëve kryesore që shfaq "Diçka shkoi keq" me një buton Rifresko, dhe e regjistron gabimin në konsolë. Mbaj headerin dhe navigimin jashtë tij, që të vazhdojnë të shfaqen.

Nuk e rregullon gabimin, por vizitorët shohin një mesazh në vend të një ekrani të bardhë, dhe ju shihni se ku u prish.

Hapi 6: Nuk ka gabime, por është bosh

Nëse konsola është e pastër dhe skriptet ngarkohen:

• Kontrolloni skedën Elements. A ka përmbajtje brenda <div id="root">? Nëse po, ajo vizatohet por është e padukshme: tekst i bardhë mbi të bardhë, opacity: 0, display: none, ose një element në ekran të plotë që e mbulon.
• Kontrolloni ruterin. Nëse asnjë rrugë nuk përputhet me URL-në aktuale dhe nuk ka një rrugë "nuk u gjet", disa rutera nuk shfaqin asgjë. Shtoni një rrugë catch-all që shfaq një faqe 404.
• Kontrolloni pikën e montimit. Kodi duhet të montohet në një element që ekziston. Nëse index.html ka id="app" dhe kodi kërkon root, nuk shfaqet asgjë (dhe React zakonisht regjistron një gabim).
• Kontrolloni një shtesë shfletuesi. Provoni një dritare private. Bllokuesit e reklamave herë pas here bllokojnë skripte me emra si analytics ose ads.

Bosh vetëm pas rifreskimit të një faqeje?

Nëse faqja kryesore funksionon, por rifreskimi i /dashboard shfaq një faqe boshe ose 404, serveri nuk di të dërgojë index.html për rrugët e aplikacionit. Ky është një problem me rezervën e rrugëzimit, i mbuluar te si të rregulloni gabimet 404 pas publikimit.

Gabimet e zakonshme

• Leximi i gabimit të fundit në vend të atij të parë. Rreshti i parë i kuq është zakonisht shkaku.
• Vendosja e variablave të mjedisit pa ri-ndërtuar. Variablat e front end-it fiksohen në kohën e ndërtimit.
• Testimi vetëm me llogarinë tuaj. Rrëzimet me llogari bosh janë një nga shkaqet më të zakonshme të faqeve boshe.
• Supozimi që publikimi u krye. Kontrolloni regjistrin e ndërtimit përpara se të debugoni kodin.
• Fajësimi i cache-it të shfletuesit për gjithçka. Një rifreskim i fortë e përjashton në disa sekonda; nëse faqja është ende bosh, shkaku është diçka tjetër.

Faqet boshe në Mythex

Nëse Preview është bosh, kontrolloni së pari që aplikacioni po ekzekutohet (hapni Code → terminal), pastaj kërkojini Mythex-it të nisë serverin e duhur, klikoni Refresh te shiriti i pamjes paraprake, ose përdorni /fix. Për një URL të publikuar bosh, dokumentacioni sugjeron të prisni një minutë dhe të bëni rifreskim të fortë, të konfirmoni që variablat e mjedisit dhe baza e të dhënave u vendosën para publikimit, dhe të kontrolloni kuotën e hostimit tuaj. Mbani mend që një aplikacion i publikuar është një fotografi: pasi rregulloni diçka, publikoni përsëri. Nëse një ndryshim e shkaktoi, Revert to this point te përgjigja e fundit e mirë e kthen projektin mbrapsht. Shihni Zgjidhja e problemeve dhe Zgjidhja e problemeve të publikimit në dokumentacion, dhe udhëzuesin tonë të përgjithshëm për diagnostikimin e një aplikacioni të ndërtuar me AI.

Lista e kontrollit për faqen e bardhë

• U lexua gabimi i parë i kuq në Console
• U kontrollua skeda Network për skedarët .js/.css që japin 404 ose kthejnë HTML
• Rruga bazë përputhet me vendin ku shërbehet aplikacioni
• Ndërtimi u krye, dhe dosja e daljes së ndërtimit është ajo që publikohet
• Të gjitha variablat e mjedisit të front end-it janë vendosur në ndërtimin aktiv, pastaj u ndërtua përsëri
• Rrëzimi u rregullua, përfshirë për llogaritë bosh dhe të reja
• Error boundary është vendosur, që gabimet e ardhshme të shfaqin një mesazh
• Rrugë catch-all për URL-të e panjohura
• U testua pas një rifreskimi të fortë dhe në një dritare private

Pyetje