Paano Ayusin ang Blangkong Puting Page sa Web App Mo

Ang blangkong puting page ay halos palaging nangangahulugan ng isa sa dalawang bagay: nag-crash ang JavaScript ng app bago pa ito nakaguhit ng anuman, o hindi kailanman nag-load ang JavaScript. Buksan ang browser console (right-click → Inspect → Console), basahin ang unang pulang error, at tingnan ang Network tab para sa mga file na hindi nag-load. Karamihan ng sanhi ay nawawalang environment variable, maling base path, build na hindi natapos, o crash sa isang component.

Sakop ng gabay na ito ang mga single-page app na ginawa gamit ang React, Vue o katulad na framework (kasama ang mga app na ginawa ng AI builders), kung saan pinakakaraniwan ang blangkong page.

Bakit blangko ang page

Ang modernong single-page app (SPA) ay nagpapadala sa browser ng halos walang lamang HTML file, humigit-kumulang ganito:

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

Saka bubuuin ng JavaScript ang buong page sa loob ng walang lamang div na iyon. Kapag nabigo ang pag-load ng script, o nagka-error bago mag-render, mananatiling walang laman ang div at puti ang makikita mo. Hindi "sira" ang page sa paraang nakikita; hindi lang ito nakaguhit.

Kaya laging nagsisimula ang ayos sa developer tools, hindi sa mismong page.

Hakbang 1: Basahin ang console

Buksan ang developer tools: right-click sa page at piliin ang Inspect, o pindutin ang F12 (Cmd+Option+I sa Mac). Pumunta sa Console tab at mag-reload ng page.

Tingnan ang unang pulang error; kadalasang side effect lang ang mga sumunod. Ang sinasabi nito ang tumuturo sa sanhi:

Mensahe sa console (karaniwang pagkakasulat)	Ibig sabihin	Pumunta sa
`Cannot read properties of undefined (reading '...')`	Inasahan ng code ang datos na wala roon	Hakbang 4
`... is not defined` / `... is not a function`	Nawawalang import, variable o setting	Hakbang 4 o Hakbang 3
`Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"`	Ang URL ng isang script ay nagbalik ng HTML page sa halip na JavaScript	Hakbang 2
`Uncaught SyntaxError: Unexpected token '<'`	Pareho: HTML kung saan inaasahan ang JavaScript	Hakbang 2
`supabaseUrl is required`, `Missing API key`, o katulad	Walang laman ang environment variable	Hakbang 3
`Access to fetch ... has been blocked by CORS policy`	Na-block ang request sa ibang domain	Tingnan ang paano ayusin ang CORS errors
Walang anumang error	Gumana ang render pero walang nakikita, o may CSS na nagtatago nito	Hakbang 6

Kopyahin ang kumpletong error text, kasama ang pangalan ng file at numero ng linya. Kung gumagamit ka ng AI builder, i-paste ito diretso sa chat.

Hakbang 2: Tingnan kung nag-load ang mga file

Buksan ang Network tab, lagyan ng tsek ang Disable cache, at mag-reload. Tingnan ang mga request para sa .js at .css na file.

Status 404 sa JavaScript file: hinihingi ng page ang file na wala sa server.
Status 200 pero text/html ang type: nagbalik ang server ng page (kadalasan mismong index.html, dahil sa SPA fallback) sa halip na script. Parehong ugat: wala ang file kung nasaan ito inaasahan ng page.

Karaniwang dahilan:

Maling base path. Kung nakahain ang app sa sub-folder, gaya ng example.com/app/, pero na-build ito para mag-load ng mga file mula sa /assets/..., mawawala ang bawat script request. Sa Vite, ito ang base option sa vite.config; sa Create React App, ang homepage field; sa Next.js, ang basePath. Dapat itong tumugma sa aktwal na lugar kung saan nakahain ang app.

Lumang index.html. Binibigyan ng build tools ng hash ang mga pangalan ng file, gaya ng index-a1b2c3.js. Pagkatapos ng bagong deploy, nawawala na ang lumang file. Kung may naka-cache pa ring lumang index.html ang browser o CDN, hihingi ito ng lumang file at walang makukuha. Nakukumpirma ito sa hard refresh (Cmd+Shift+R o Ctrl+Shift+R). Ang pangmatagalang ayos ay ang pagsilbi ng index.html na may maikli o walang cache na header, habang matagal na naka-cache ang mga hashed file.

Hindi natapos o hindi na-deploy ang build. Kung pumalpak ang build, maaaring luma o walang laman na output folder ang sineserbisyo ng host. Tingnan ang build log para sa mga error.

Maling folder ang na-publish. Dapat ihain ng host ang build output (kadalasang dist o build), hindi ang source folder ng project. Kapag source ang inihain, makakakuha ka ng index.html na nakaturo sa /src/main.tsx, na hindi kayang patakbuhin ng browser.

Hakbang 3: Tingnan ang environment variables

Kadalasang binabasa ng frontend apps ang mga setting gaya ng API URL o public key sa build time. Kapag nawawala ang variable sa live build, agad mag-throw ang code gaya ng createClient(undefined, undefined), at nagiging puti ang page.

Mga dapat malaman:

Sa Vite, tanging mga variable na may prefix na VITE_ ang available sa browser code, binabasa bilang import.meta.env.VITE_NAME. Sa Create React App, REACT_APP_; sa Next.js, NEXT_PUBLIC_.
Ang mga halagang ito ay naka-bake sa oras ng build. Ang pagdaragdag ng variable pagkatapos ng build ay walang epekto hangga't hindi ka nagbu-build at nagde-deploy muli.
Maaaring may .env file ang preview o lokal na makina na wala sa production build. Itakda ang parehong variable sa host.
Anumang may mga prefix na ito ay napupunta sa public JavaScript. Mga public na halaga lang ang ilagay doon, hindi kailanman secret keys.

Mabilis na test: hanapin sa console error ang undefined sa tabi ng pangalan ng setting, o itanong:

Nagpapakita ng blangkong page ang na-publish na app. Ilista ang bawat environment variable na binabasa ng frontend, tingnan kung alin ang nawawala o walang laman sa live build, at gawing malinaw na mensahe ng error ang app sa halip na blangkong page kapag may nawawala.

Hakbang 4: Ayusin ang crash

Kung normal na JavaScript error ang nasa console, nag-crash ang code habang nagre-render. Mga karaniwang sanhi sa mga app na ginawa ng AI:

Wala pa ang datos. Binabasa ng component ang user.name bago dumating ang user. Ang ayos ay loading state, o optional chaining (user?.name).
Walang laman na datos. Walang records ang bagong account, at ipinapalagay ng code na may kahit isang item ang listahan.
Hindi inaasahang hugis ng datos. Nagbalik ang API ng error object sa halip na listahang inaasahan ng code.
Nawawalang import matapos mapalitan ng pangalan o mailipat ang isang file.
Paggamit ng browser-only API habang nasa server-side rendering, gaya ng window o localStorage sa Next.js server component.

Ibigay sa AI ang buong error, ang page, at kung sino ang naka-log in:

Blangko ang Dashboard page para sa mga bagong user. Console: TypeError: Cannot read properties of undefined (reading 'map') sa ProjectList.tsx:18. Gumagana ito sa account ko, na may mga project. Ayusin para ang walang lamang account ay magpakita ng "No projects yet", at tingnan ang bagong account sa preview.

Hakbang 5: Magdagdag ng error boundary

Sa React, maaaring alisin ng isang nagka-crash na component ang buong app, kaya nagiging ganap na blangko ang page dahil sa maliit na bug. Ang error boundary ay component na humuhuli ng mga render error sa ibaba nito at nagpapakita ng fallback.

Magdagdag ng error boundary sa mga pangunahing route na nagpapakita ng "Something went wrong" na may Reload button, at nagla-log ng error sa console. Panatilihing nasa labas ng boundary ang header at navigation para tuloy pa rin silang mag-render.

Hindi nito inaayos ang bug, pero nakakakita ang mga bisita ng mensahe sa halip na blangkong screen, at makikita mo kung saan ito nasira.

Hakbang 6: Walang error, blangko pa rin

Kung malinis ang console at nag-load ang mga script:

Tingnan ang Elements tab. May content ba sa loob ng <div id="root">? Kung meron, nagre-render ito pero hindi nakikita: puting text sa puting background, opacity: 0, display: none, o elementong nakatakip sa buong screen.
Tingnan ang router. Kung walang route na tumutugma sa kasalukuyang URL at walang "not found" route, may mga router na walang inilalabas. Magdagdag ng catch-all route na nagpapakita ng 404 page.
Tingnan ang mount point. Dapat mag-mount ang code sa elementong umiiral. Kung may id="app" ang index.html pero hinahanap ng code ang root, walang lalabas (at kadalasang maglo-log ng error ang React).
Tingnan ang browser extension. Subukan sa private window. Paminsan-minsang hina-harangan ng ad blockers ang mga script na may pangalang gaya ng analytics o ads.

Blangko lang pagkatapos mag-refresh ng page?

Kung gumagana ang home page pero ang pag-refresh ng /dashboard ay nagpapakita ng blangko o 404, hindi alam ng server na dapat magpadala ng index.html para sa mga app route. Problema iyon ng routing fallback, na sakop ng paano ayusin ang 404 errors pagkatapos mag-deploy.

Mga karaniwang pagkakamali

Pagbasa sa huling error sa halip na sa una. Ang unang pulang linya ang kadalasang sanhi.
Pagtatakda ng environment variables nang hindi nagre-rebuild. Naka-fix ang frontend variables sa oras ng build.
Pagsubok lang gamit ang sarili mong account. Isa sa pinakakaraniwang sanhi ng blangkong page ang crash sa walang laman na account.
Pag-aakalang nagtagumpay ang deploy. Tingnan ang build log bago i-debug ang code.
Pagsisisi sa browser cache sa lahat. Inaalis ito ng hard refresh sa ilang segundo; kung blangko pa rin ang page, iba ang problema.

Mga blangkong page sa Mythex

Kung blangko ang Preview, tingnan muna kung tumatakbo ang app (buksan ang Code → terminal), saka hilingin sa Mythex na simulan ang tamang server, i-click ang Refresh sa preview toolbar, o gamitin ang /fix. Para sa blangkong na-publish na URL, sinasabi ng docs na maghintay ng isang minuto at mag-hard-refresh, kumpirmahing naitakda ang env vars at database bago mag-publish, at tingnan ang hosting allowance mo. Tandaan na snapshot ang na-publish na app: pagkatapos ng ayos, mag-publish muli. Kung ang isang pagbabago ang sanhi, ang Revert to this point sa huling magandang reply ay nagbabalik ng project. Tingnan ang Troubleshooting at Publish troubleshooting sa docs, at ang pangkalahatan naming gabay sa pag-debug ng app na ginawa ng AI.

Checklist ng blangkong page

Nabasa ang unang pulang error sa Console
Tiningnan ang Network tab para sa .js/.css na nagbibigay ng 404 o nagbabalik ng HTML
Tumutugma ang base path sa lugar kung saan nakahain ang app
Natapos ang build, at ang build output folder ang naka-publish
Nakatakda ang lahat ng frontend environment variables sa live build, saka nag-rebuild
Naayos ang crash, kasama para sa walang laman at bagong account
May error boundary para magpakita ng mensahe ang mga susunod na crash
May catch-all route para sa hindi kilalang URL
Nasubukan pagkatapos ng hard refresh at sa private window

Mga tanong

Bakit blangkong puting page ang React app ko?

Kadalasan dahil nag-crash ang JavaScript bago pa makapag-render ng anuman, o dahil hindi kailanman nag-load ang JavaScript file. Buksan ang browser console: ang pulang error doon ang magsasabi kung alin, at ang file at linya kung saan ito nangyari.

Bakit gumagana ang app ko sa local pero blangkong page pagkatapos mag-deploy?

Ang pinakakaraniwang sanhi ay mga environment variable na hindi kailanman naitakda para sa live build, mga JavaScript at CSS file na hinihingi sa maling path (hindi tugma ang base path), at isang lumang naka-cache na index.html na nakaturo sa mga file na wala na.

Ano ang ibig sabihin ng 'Failed to load module script'?

Humingi ang browser ng JavaScript file pero HTML page ang ibinalik, kadalasan ang index.html ng site o isang error page. Mali ang path ng file o wala ito sa server, kaya tingnan ang build output at ang setting ng base path ng app.

Paano ko pipigilan ang isang bug na magpablangko ng buong page?

Magdagdag ng error boundary. Sa React, ang error boundary ay component na humuhuli ng mga render error sa bahaging nasa ibaba nito at nagpapakita ng fallback message sa halip na alisin ang lahat.