Jinsi ya Kurekebisha Ukurasa Mweupe Tupu kwenye Web App Yako

Ukurasa mweupe tupu karibu kila wakati unamaanisha mojawapo ya mambo mawili: JavaScript ya app ilianguka kabla ya kuchora chochote, au JavaScript haikupakia kabisa. Fungua console ya kivinjari (bonyeza kulia → Inspect → Console) kisha usome hitilafu ya kwanza nyekundu, kisha angalia kichupo cha Network kwa faili zilizoshindwa kupakia. Sababu nyingi ni environment variable inayokosekana, njia ya msingi isiyo sahihi, build isiyomaliza, au kuanguka kwa kipengele kimoja.

Mwongozo huu unahusu app za ukurasa mmoja zilizojengwa kwa React, Vue au frameworks zinazofanana (ikiwemo app zilizotengenezwa na zana za kujenga za AI), ambako kurasa tupu ni za kawaida zaidi.

Kwa nini ukurasa ni mweupe

App ya kisasa ya ukurasa mmoja (SPA) inamtumia kivinjari HTML karibu tupu, takriban kama hivi:

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

Kisha JavaScript inajenga ukurasa wote ndani ya div hiyo tupu. Ikiwa script haipakii, au inatupa hitilafu kabla ya kuchora, div inabaki tupu na unaona nyeupe. Ukurasa hauko "umevunjika" kwa namna inayoonekana; haujachorwa tu.

Ndiyo maana urekebishaji daima unaanzia kwenye zana za msanidi, si kwenye ukurasa wenyewe.

Hatua ya 1: Soma console

Fungua zana za msanidi: bonyeza kulia kwenye ukurasa na uchague Inspect, au bonyeza F12 (Cmd+Option+I kwenye Mac). Nenda kwenye kichupo cha Console kisha onyesha upya ukurasa.

Tazama hitilafu ya kwanza nyekundu; zinazofuata mara nyingi ni madhara ya ile ya kwanza. Kile inachosema kinaelekeza kwenye sababu:

Ujumbe wa console (maneno ya kawaida)	Maana yake	Nenda
`Cannot read properties of undefined (reading '...')`	Msimbo ulitarajia data isiyokuwepo	Hatua ya 4
`... is not defined` / `... is not a function`	Import, kigezo au mpangilio unaokosekana	Hatua ya 4 au Hatua ya 3
`Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"`	URL ya script ilirudisha ukurasa wa HTML badala ya JavaScript	Hatua ya 2
`Uncaught SyntaxError: Unexpected token '<'`	Jambo lilelile: HTML ambapo JavaScript ilitarajiwa	Hatua ya 2
`supabaseUrl is required`, `Missing API key`, au kitu kama hicho	Environment variable ni tupu	Hatua ya 3
`Access to fetch ... has been blocked by CORS policy`	Ombi kwa domeni nyingine lilizuiwa	Tazama jinsi ya kurekebisha makosa ya CORS
Hakuna hitilafu kabisa	Uchoraji ulifanya kazi lakini unaonyesha chochote, au CSS inaficha	Hatua ya 6

Nakili maandishi kamili ya hitilafu, ikiwemo jina la faili na nambari ya mstari. Ukitumia zana ya kujenga ya AI, ibandike moja kwa moja kwenye gumzo.

Hatua ya 2: Angalia kama faili zilipakia

Fungua kichupo cha Network, weka alama kwenye Disable cache, kisha onyesha upya. Angalia maombi ya faili za .js na .css.

Hali 404 kwenye faili la JavaScript: ukurasa unaomba faili lisilo kwenye server.
Hali 200 lakini aina ni text/html: server imerudisha ukurasa (mara nyingi index.html yenyewe, kwa sababu ya fallback ya SPA) badala ya script. Chanzo ni kile kile: faili halipo mahali ukurasa unapolitarajia.

Sababu za kawaida:

Njia ya msingi isiyo sahihi. Ikiwa app inatolewa kutoka folda ndogo, kama example.com/app/, lakini ilijengwa kupakia faili kutoka /assets/..., kila ombi la script litakosa. Kwenye Vite hii ni chaguo la base kwenye vite.config; kwenye Create React App ni uwanja wa homepage; kwenye Next.js ni basePath. Lazima ilingane na mahali app inapotolewa kweli.

index.html iliyopitwa na wakati. Zana za build hupa faili majina yenye hash ya yaliyomo, kama index-a1b2c3.js. Baada ya deploy mpya, faili la zamani linapotea. Ikiwa kivinjari au CDN bado ina index.html ya zamani kwenye cache, inaomba faili la zamani na haipati chochote. Onyesho la nguvu (Cmd+Shift+R au Ctrl+Shift+R) linathibitisha hili. Suluhisho la muda mrefu ni kutoa index.html yenye header fupi au isiyo na cache, huku faili zenye hash zikihifadhiwa kwa muda mrefu.

Build haikumaliza au haikuwekwa hewani. Ikiwa build ilishindwa, host pengine inatoa folda ya matokeo ya zamani au tupu. Angalia kumbukumbu ya build kwa makosa.

Folda mbaya imechapishwa. Host lazima itoe matokeo ya build (kwa kawaida dist au build), si folda ya chanzo ya mradi. Kutoa chanzo kunakupa index.html inayoelekeza kwenye /src/main.tsx, ambayo kivinjari hakiwezi kuiendesha.

Hatua ya 3: Angalia environment variables

App za frontend mara nyingi husoma mipangilio kama URL ya API au funguo ya umma wakati wa build. Ikiwa variable haipo kwenye build ya moja kwa moja, msimbo kama createClient(undefined, undefined) unatupa hitilafu papo hapo, na ukurasa unageuka mweupe.

Mambo ya kujua:

Kwenye Vite, variables zenye kiambishi VITE_ pekee zinapatikana kwenye msimbo wa kivinjari, zinazosomwa kama import.meta.env.VITE_NAME. Kwenye Create React App ni REACT_APP_; kwenye Next.js ni NEXT_PUBLIC_.
Thamani hizi zinawekwa ndani ya build wakati app inajengwa. Kuongeza variable baada ya build hakufanyi chochote mpaka ujenge na kuweka hewani tena.
Preview au kompyuta yako ya ndani inaweza kuwa na faili la .env ambalo build ya uzalishaji haina. Weka variables zile zile kwenye host.
Chochote chenye viambishi hivi kinaishia kwenye JavaScript ya umma. Weka thamani za umma pekee humo, kamwe funguo za siri.

Jaribio la haraka: tafuta undefined karibu na jina la mpangilio kwenye hitilafu ya console, au uliza:

Ukurasa uliochapishwa unaonyesha ukurasa mweupe tupu. Orodhesha kila environment variable ambayo frontend inasoma, kagua zipi hazipo au ni tupu kwenye build ya moja kwa moja, na fanya app ionyeshe ujumbe wazi wa hitilafu badala ya ukurasa mweupe pale moja inapokosekana.

Hatua ya 4: Rekebisha kuanguka

Ikiwa console inaonyesha hitilafu ya kawaida ya JavaScript, msimbo ulianguka wakati wa kuchora. Sababu za kawaida kwenye app za AI:

Data bado haijapakia. Kipengele kinasoma user.name kabla user haijafika. Suluhisho ni hali ya kupakia, au optional chaining (user?.name).
Data tupu. Akaunti mpya haina rekodi, na msimbo unadhani orodha ina angalau kipengee kimoja.
Umbo lisilotarajiwa la data. API ilirudisha kitu cha hitilafu badala ya orodha ambayo msimbo ulitarajia.
Import inayokosekana baada ya faili kubadilishwa jina au kuhamishwa.
Kutumia API ya kivinjari pekee wakati wa server-side rendering, kama window au localStorage kwenye server component ya Next.js.

Mpe AI hitilafu kamili, ukurasa, na jina la akaunti uliyoingia nayo:

Ukurasa wa Dashboard ni mweupe tupu kwa watumiaji wapya. Console: TypeError: Cannot read properties of undefined (reading 'map') kwenye ProjectList.tsx:18. Unafanya kazi kwa akaunti yangu, ambayo ina miradi. Irekebishe ili akaunti tupu ionyeshe "Hakuna miradi bado", na uangalie akaunti mpya kwenye preview.

Hatua ya 5: Ongeza error boundary

Katika React, kipengele kimoja kinachoanguka kinaweza kuondoa app nzima, ndiyo sababu hitilafu ndogo inazalisha ukurasa mweupe kabisa. Error boundary ni kipengele kinachokamata hitilafu za kuchora chini yake na kuonyesha akiba.

Ongeza error boundary kuzunguka njia kuu zinazoonyesha "Kuna kitu kimeenda vibaya" pamoja na kitufe cha Reload, na uandike hitilafu kwenye console. Weka kichwa na urambazaji nje yake ili viendelee kuchora.

Haisuluhishi hitilafu, lakini wageni wanaona ujumbe badala ya skrini tupu, nawe unaona ilipovunjika.

Hatua ya 6: Hakuna hitilafu, bado tupu

Ikiwa console ni safi na scripts zinapakia:

Angalia kichupo cha Elements. Je, kuna maudhui ndani ya <div id="root">? Ikiwa ndiyo, inachora lakini haionekani: maandishi meupe kwenye nyeupe, opacity: 0, display: none, au kipengele cha skrini nzima kinachofunika.
Angalia router. Ikiwa hakuna route inayolingana na URL ya sasa na hakuna route ya "haipatikani", baadhi ya routers hazichori chochote. Ongeza route ya kukamata yote inayoonyesha ukurasa wa 404.
Angalia mahali pa kuunganisha. Msimbo lazima uunganishe kwenye kipengele kilichopo. Ikiwa index.html ina id="app" na msimbo unatafuta root, hakuna kitakachoonekana (na React kwa kawaida huandika hitilafu).
Angalia nyongeza ya kivinjari. Jaribu dirisha la faragha. Vizuizi vya matangazo wakati mwingine huzuia scripts zenye majina kama analytics au ads.

Ukurasa tupu tu baada ya kuonyesha upya?

Ikiwa ukurasa wa nyumbani unafanya kazi lakini kuonyesha upya /dashboard kunaonyesha ukurasa tupu au 404, server haijui kutuma index.html kwa njia za app. Hilo ni tatizo la fallback ya routing, linalofunikwa katika jinsi ya kurekebisha makosa ya 404 baada ya kuweka hewani.

Makosa ya kawaida

Kusoma hitilafu ya mwisho badala ya ya kwanza. Mstari wa kwanza mwekundu kwa kawaida ndio sababu.
Kuweka environment variables bila kujenga upya. Variables za frontend zimewekwa wakati wa build.
Kujaribu kwa akaunti yako pekee. Kuanguka kwa akaunti tupu ni mojawapo ya sababu za kawaida za ukurasa mweupe.
Kudhani deploy ilifanikiwa. Angalia kumbukumbu ya build kabla ya kurekebisha msimbo.
Kulaumu cache ya kivinjari kwa kila kitu. Onyesho la nguvu linaondoa hilo kwa sekunde; ikiwa ukurasa bado ni mweupe, ni kitu kingine.

Kurasa tupu kwenye Mythex

Ikiwa Preview ni tupu, kwanza hakikisha app inaendeshwa (fungua Code → terminal), kisha omba Mythex aanzishe server sahihi, bonyeza Refresh kwenye upau wa preview, au tumia /fix. Kwa URL ya kuchapishwa tupu, docs zinapendekeza kusubiri dakika moja na kuonyesha upya kwa nguvu, kuthibitisha env vars na database zilisanidiwa kabla ya kuchapisha, na kuangalia kiwango chako cha hosting. Kumbuka kwamba app iliyochapishwa ni picha ya wakati fulani: baada ya kurekebisha kitu, chapisha tena. Ikiwa mabadiliko fulani ndiyo yalisababisha, bonyeza Rudi kwenye hatua hii kwenye jibu la mwisho zuri ili kurudisha mradi nyuma. Tazama Utatuzi na Utatuzi wa uchapishaji kwenye docs, pamoja na mwongozo wetu wa jumla wa kutatua app iliyojengwa kwa AI.

Orodha ya ukurasa mweupe

Nimesoma hitilafu ya kwanza nyekundu kwenye Console
Nimeangalia kichupo cha Network kwa faili za .js/.css zinazotoa 404 au HTML
Njia ya msingi inalingana na mahali app inapotolewa
Build imemalizika, na folda ya matokeo ya build ndiyo inayochapishwa
Environment variables zote za frontend zimewekwa kwenye build ya moja kwa moja, kisha zimejengwa upya
Kuanguka kumerekebishwa, ikiwemo kwa akaunti tupu na mpya
Error boundary ipo ili hitilafu za baadaye zionyeshe ujumbe
Route ya kukamata yote kwa URL zisizojulikana
Nimejaribu baada ya onyesho la nguvu na kwenye dirisha la faragha

Maswali

Kwa nini app yangu ya React inaonyesha ukurasa mweupe tupu?

Mara nyingi ni kwa sababu JavaScript ilianguka kabla ya kuchora chochote, au faili la JavaScript halikupakia kabisa. Fungua console ya kivinjari: hitilafu nyekundu huko inakuambia ni ipi, pamoja na faili na mstari ilipotokea.

Kwa nini app yangu inafanya kazi kwenye kompyuta yangu lakini inaonyesha ukurasa tupu baada ya kuweka hewani?

Sababu za kawaida zaidi ni environment variables ambazo hazikuwekwa kwa build ya uzalishaji, faili za JavaScript na CSS zinazoombwa kutoka njia isiyo sahihi (kutolingana kwa njia ya msingi), na index.html iliyohifadhiwa kwenye cache inayoelekeza kwenye faili ambazo hazipo tena.

'Failed to load module script' inamaanisha nini?

Kivinjari kiliomba faili la JavaScript na kikapata ukurasa wa HTML badala yake, kwa kawaida index.html ya tovuti au ukurasa wa hitilafu. Njia ya faili si sahihi au faili halipo kwenye server, kwa hiyo angalia matokeo ya build na mpangilio wa njia ya msingi wa app.

Ninawezaje kuzuia hitilafu moja isifanye ukurasa mzima uwe mweupe?

Ongeza error boundary. Kwenye React, error boundary ni kipengele kinachokamata hitilafu za kuchora kwenye sehemu ya ukurasa iliyo chini yake na kuonyesha ujumbe wa akiba badala ya kuondoa kila kitu.