Sida loo hagaajiyo bog cad oo madhan web app-kaaga

Bog cad oo madhan waxay badanaa ka dhigan tahay mid ka mid ah laba shay: JavaScript-ka app-ka wuu burbursaday ka hor intuusan wax sawirin, ama JavaScript-ka waligiis ma soo rarin. Fur console-ka browser-ka (midig-riix → Inspect → Console) oo akhri qaladka cas ee ugu horreeya, kadibna hubi tab-ka Network faylasha ku guuldareystay inay soo rarmaan. Sababaha ugu badan waa env variable maqan, base path khaldan, build aan dhammaan, ama crash ku yimid hal component.

Hagahan wuxuu daboolayaa single-page apps lagu dhisay React, Vue ama framework-yo la mid ah (oo ay ku jiraan apps ay sameeyeen AI builders), taas oo ah meesha ay bogagga madhanka ahi inta badan ka dhacaan.

Sababta bogga uu cad yahay

Single-page app (SPA) casri ah wuxuu browser-ka u diraa faylka HTML oo ku dhow madhan, qiyaastii sidan:

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

Kadibna JavaScript-ku wuxuu dhisaa bogga oo dhan gudaha div-ka madhan. Haddii script-ku soo rarin waayo, ama uu khalad ku tuuro ka hor intaanu render gareyn, div-ku wuu madhan yahay oo waxaad aragtaa cad. Bogga “burbursan” ma aha si muuqda; wuxuu kaliya waligiis lama sawirin.

Sidaas darteed hagaajinta had iyo jeer waxay ka bilaabataa developer tools, ma aha bogga laftiisa.

Tallaabo 1: Akhri console-ka

Fur developer tools: midig-riix bogga oo dooro Inspect, ama riix F12 (Cmd+Option+I Mac-ka). U gudub tab-ka Console oo dib u cusboonaysii bogga.

Eeg qaladka cas ee ugu horreeya; kuwa dambe badanaa waa saameyn dhinac ah. Waxa uu sheegayo wuxuu tilmaamayaa sababta:

Fariinta console-ka (qaabka caadiga ah)	Macnaha	Tag
`Cannot read properties of undefined (reading '...')`	Code-ku wuxuu filayay xog aan halkaas jirin	Tallaabo 4
`... is not defined` / `... is not a function`	Import, doorsoome ama dejin maqan	Tallaabo 4 ama Tallaabo 3
`Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"`	URL-ka script-ka wuxuu soo celiyay bog HTML ah halkii JavaScript	Tallaabo 2
`Uncaught SyntaxError: Unexpected token '<'`	Isla shay: HTML halkii JavaScript laga filayay	Tallaabo 2
`supabaseUrl is required`, `Missing API key`, ama wax la mid ah	Doorsoomaha deegaanka waa madhan yahay	Tallaabo 3
`Access to fetch ... has been blocked by CORS policy`	Codsi domain kale loo diray ayaa la xidhay	Eeg sida loo hagaajiyo CORS errors
Ma jiro qalad	Render-ku wuu shaqeeyay laakiin wax ma muujinayo, ama CSS ayaa qarinaya	Tallaabo 6

Koobi qoraalka qaladka oo dhan, oo ay ku jiraan magaca faylka iyo lambarka safka. Haddii aad isticmaasho AI builder, ku dheji chat-ka toos.

Tallaabo 2: Hubi in faylasha la soo raray

Fur tab-ka Network, calaamadi Disable cache, oo dib u cusboonaysii. Eeg codsiyada faylasha .js iyo .css.

Status 404 faylka JavaScript: bogga wuxuu codsanayaa fayl aan server-ka ku jirin.
Status 200 laakiin nooca waa text/html: server-ku wuxuu soo celiyay bog (inta badan index.html laftiisa, sababtoo ah SPA fallback) halkii script-ka. Sababta asaasiga ah waa isku mid: faylku ma joogo meesha bogga uu filayo.

Sababaha caadiga ah:

Base path khaldan. Haddii app-ka lagu adeego folder hoose, sida example.com/app/, laakiin loo dhisay inuu faylasha ka soo rarto /assets/..., codsi script kasta wuu sii luntaa. Vite-ka tani waa xulashada base ee vite.config; Create React App-ka waa goobta homepage; Next.js-ka waa basePath. Waa inay waafaqaan meesha app-ka dhab ahaan loo adeegayo.

index.html duugoobay. Qalabyada build-ka faylasha waxay siiyaan magacyo leh hash-ka nuxurka, sida index-a1b2c3.js. Geynta cusub ka dib, faylkii hore wuu baabbi'ay. Haddii browser ama CDN weli kaydinayo index.html-kii hore, wuxuu codsanayaa faylkii hore oo wax ma helo. Hard refresh (Cmd+Shift+R ama Ctrl+Shift+R) ayaa xaqiijinaya tan. Xalka muddada dheer waa in index.html loo adeego header cache-ka gaaban ama aan lahayn, halka faylasha hash leh loo kaydiyo muddo dheer.

Build-ku ma dhammaan ama lama geyn. Haddii build-ku fashilmay, host-ku waxa laga yaabaa inuu adeegayo folder output ah oo duugoobay ama madhan. Hubi build log-ka qaladaadka.

Folder khaldan ayaa la daabacay. Host-ku waa inuu adeegaa output-ka build-ka (caadi ahaan dist ama build), ma aha folder-ka source-ka mashruuca. Adeegidda source-ka waxay kuu siinaysaa index.html oo tilmaamaya /src/main.tsx, kaas oo browser-ku aanu socon karin.

Tallaabo 3: Hubi doorsoomayaasha deegaanka

Apps-ka frontend-ka badanaa wuxuu akhriyaa dejinno sida API URL ama public key waqtiga build-ka. Haddii doorsoome ka maqan yahay build-ka toosa, code sida createClient(undefined, undefined) isla markiiba wuu burburaa, bogguna wuu cad yahay.

Waxyaabo la ogaado:

Vite-ka, doorsoomayaasha kaliya ee lagu bilaabo VITE_ ayaa lagu heli karaa code-ka browser-ka, waxaana lagu akhriyaa import.meta.env.VITE_NAME. Create React App-ka waa REACT_APP_; Next.js-ka, NEXT_PUBLIC_.
Qiyamkan waxaa lagu dhejiyaa markii app-ka la dhisayo. Doorsoome kadib build-ka lagu daro waxba ma sameynayo ilaa aad dib u dhisto oo dib u geyso.
Kombiyuutarka local-ka ama preview-ku waxa laga yaabaa inuu leeyahay fayl .env oo build-ka production-ka aanu lahayn. Dhig isla doorsoomayaasha host-ka.
Wax kasta oo leh horjoogayaashan wuxuu ku dhammaadaa JavaScript dadweyne. Halkaas ku dhig oo kaliya qiyamka dadweynaha, waligaa furayaasha qarsoon ha dhigin.

Tijaabo degdeg ah: raadi qaladka console-ka oo ay ku jirto undefined oo u dhow magaca dejin, ama weydii:

Bogga la daabacay wuxuu muujinayaa bog madhan. Liiji doorsoomayaasha deegaanka oo dhan ee frontend-ku akhriyo, hubi kuwa maqan ama madhan ee live build-ka, oo ka dhig app-ka inuu muujiyo fariin cad oo qalad ah halkii uu bog madhan ka muuqan lahaa marka mid maqan yahay.

Tallaabo 4: Hagaaji crash-ka

Haddii console-ku muujiyo qalad JavaScript oo caadi ah, code-ku wuu burburay render-ka. Sababaha caadiga ah ee apps-ka AI lagu dhisay:

Xogta weli lama soo rarin. Component-ku wuxuu akhriyaa user.name ka hor inta user la yimaado. Xalku waa state loading, ama optional chaining (user?.name).
Xog madhan. Akoon cusub ma leh diiwaano, code-ku wuxuu u malaynayaa in liistadu leedahay ugu yaraan hal shay.
Qaab xog oo aan la filayn. API-gu wuxuu soo celiyay object qalad halkii liistada uu code-ku filayay.
Import maqan kadib markii fayl la magacaabay ama la raray.
Isticmaalka API-ga browser-ka oo kaliya intii server-side rendering, sida window ama localStorage server component Next.js ah.

AI-ga siiso qaladka oo dhan, bogga, iyo cidda aad ku gashay:

Bogga Dashboard-ka wuu cad yahay isticmaalayaasha cusub. Console: TypeError: Cannot read properties of undefined (reading 'map') ee ProjectList.tsx:18. Akoonkeyga waa shaqeeyaa, oo leeyahay mashaariic. Hagaaji si akoon madhan u muujiyo "No projects yet", oo hubi akoon cusub preview-ka.

Tallaabo 5: Ku dar error boundary

React-ka, hal component oo burburaya ayaa bogga oo dhan ka saari karta, taasina waa sababta cillad yar u keento bog gebi ahaanba madhan. Error boundary waa component qabta khaladaadka render-ka ee hoosteeda ah oo halkiisa fallback muujiya.

Ku dar error boundary wareega routes-ka ugu muhiimsan oo muujiya "Something went wrong" oo leh badhanka Reload, oo qaladka u diraya console-ka. Header-ka iyo navigation-ka ka dhig dibadda, si ay weli u muuqdaan.

Ma xalinayo cillada, laakiin booqdayaashu waxay arkaan fariin halkii ay ka arki lahaayeen shaashad madhan, adna waxaad aragtaa meesha ay ku burburtay.

Tallaabo 6: Qalad ma jiro, laakiin wali waa madhan

Haddii console-ku nadiif yahay oo scripts-ka la soo rarayo:

Hubi tab-ka Elements. Ma jiraa waxyaabo ku jira gudaha <div id="root">? Haddii haa, waa render la sameeyay laakiin waa aragti la'aan: qoraal cad oo cad, opacity: 0, display: none, ama element shaashadda oo dhan qarinaya.
Hubi router-ka. Haddii aanu route ku habboonayn URL-ka hadda oo aanu jirin route "not found", router-ka qaarkood waxba ma soo bandhigaan. Ku dar route catch-all oo muujiya bog 404 ah.
Hubi mount point-ka. Code-ku waa inuu ku rakibaa element jira. Haddii index.html leedahay id="app" code-kuna raadinayo root, waxba ma muuqan doonaan (React-na badanaa wuxuu log-gareeyaa qalad).
Hubi browser extension-ka. Isku day window gaar ah (private). Ad blockers-ku mararka qaarkood waxay xidhaan scripts-ka magacyada sida analytics ama ads.

Bogga madhan kaliya marka aad cusboonaysiiso?

Haddii bogga hore shaqeeyo laakiin cusboonaysiinta /dashboard ay muujiso bog madhan ama 404, server-ku ma garanayo inuu u dirayo index.html routes-ka app-ka. Taasi waa dhibaato routing fallback ah, oo ay daboolayso sida loo hagaajiyo 404 ka dib geynta.

Khaladaadka caadiga ah

In la akhriyo qaladka ugu dambeeya halkii ugu horreeya. Safka cas ee ugu horreeya badanaa waa sababta.
Doorsoomayaasha deegaanka dejinta iyada oo aan dib loo dhisin. Doorsoomayaasha frontend-ka waxay go'an yihiin waqtiga build-ka.
Tijaabinta oo keliya akoonkaaga. Crash-yada akoonka madhan waa mid ka mid ah sababaha bogga madhanka ee ugu badan.
Ka dhigista geynta inay shaqeysay. Hubi build log-ka ka hor intaadan code-ka debug-gareyn.
Cache-ka browser-ka oo loo eedeeyo wax kasta. Hard refresh wuu iska diraa dhacdadaas ilbiriqsiyo gudahood; haddii bogga weli madhan yahay, waa wax kale.

Bogagga madhan ee Mythex

Haddii Preview ay madhan tahay, marka hore hubi in app-ku socdo (fur Code → terminal), kadibna weydii Mythex inuu bilaabo server-ka saxda ah, riix Refresh toolbar-ka preview-ka, ama isticmaal /fix. Bogga la daabacay ee madhan, docs-ku wuxuu soo jeedinayaa inaad sugto daqiiqad oo aad hard-refresh samayso, hubiso in doorsoomayaasha deegaanka iyo database-ku la dejiyay ka hor daabacaadda, iyo inaad hubiso xaddiga hosting-kaaga. Xusuusnow in app-ka la daabacay uu yahay snapshot: ka dib hagaajinta, dib u daabac. Haddii isbeddel uu sababay, Revert to this point jawaabta wanaagsan ee ugu dambaysa ayaa soo celinaysa mashruuca. Eeg Troubleshooting iyo Publish troubleshooting docs-ka, iyo hagahayaga guud ee debugging app AI lagu dhisay.

Liiska bogga madhan

Akhri qaladka cas ee ugu horreeya Console-ka
Hubi tab-ka Network faylasha .js/.css ee 404 siiya ama HTML soo celiya
Base path-ku wuxuu waafaqsan yahay meesha app-ka la adeegayo
Build-ku wuu dhammaaday, folder-ka output-ka build-kuna waa kan la daabacay
Doorsoomayaasha deegaanka ee frontend-ka oo dhan waa lagu dejiyay build-ka toosa, kadibna dib loo dhisay
Crash-ka waa la hagaajiyay, oo ay ku jiraan akoonada madhan iyo kuwa cusub
Error boundary waa la dhigay si crashes-ka soo socda fariin u muujiyaan
Route catch-all URL-yada aan la aqoon
Waa la tijaabiyay ka dib hard refresh iyo window private ah

Su'aalaha

Maxaa sababa app-kaaga React uu bog cad oo madhan muujiyo?

Badanaa sababtoo ah JavaScript-ku wuu burbursaday ka hor intaan wax la muujin, ama faylka JavaScript-ka waligiis lama soo rarin. Console-ka browser-ka fur: qalad cas ku jira ayaa kuu sheeya kii iyo faylka iyo sadarka meesha uu ka dhacay.

Maxaa sababa app-kaagu kombiyuutarka ku shaqeeyo laakiin geynta ka dib bog madhan muujiyo?

Sababaha ugu badan waa env variables aan waligood loogu dejin build-ka toosa, JavaScript iyo CSS oo laga codsaday jid khaldan (base path aan waafaqsanayn), iyo index.html kaydsan oo tilmaamaya faylal aan jirin mar dambe.

Waa maxay macnaha 'Failed to load module script'?

Browser-ku wuxuu codsaday fayl JavaScript wuxuuna helay bog HTML ah halkiisa, badanaa index.html-ka site-ka ama bog qalad. Jidka faylka waa khaldan ama faylku server-ka ma jiro, sidaas darteed hubi output-ka build-ka iyo dejinta base path-ka app-ka.

Sidee u joojin karaa in cillad keliya bogga oo dhan madhiso?

Ku dar error boundary. React-ka, error boundary waa component qabta khaladaadka render-ka qaybta bogga ee hoosteeda ah oo muujisa fariin dhabarka ah halkii uu wax walba ka saari lahaa.