Com arreglar una pàgina en blanc a la teva app web

Una pàgina en blanc gairebé sempre vol dir una de dues coses: el JavaScript de l’app ha fallat abans de dibuixar res, o el JavaScript no s’ha carregat mai. Obre la consola del navegador (clic dret → Inspecciona → Consola) i llegeix el primer error en vermell, després revisa la pestanya Xarxa per trobar els fitxers que no s’han carregat. La majoria de causes són una variable d’entorn que falta, una ruta base incorrecta, una compilació que no ha acabat o un error en un sol component.

Aquesta guia tracta de les apps d’una sola pàgina construïdes amb React, Vue o frameworks similars (incloses les apps fetes per constructors amb IA), que és on més sovint apareixen les pàgines en blanc.

Per què la pàgina està en blanc

Una aplicació d’una sola pàgina (SPA) moderna envia al navegador un fitxer HTML gairebé buit, més o menys així:

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

Després, el JavaScript construeix tota la pàgina dins d’aquell div buit. Si el script no es carrega, o llança un error abans de renderitzar, el div queda buit i veus el blanc. La pàgina no està «trencada» de manera visible; simplement no s’ha dibuixat mai.

Per això la solució sempre comença a les eines de desenvolupador, no a la pàgina en si.

Pas 1: llegeix la consola

Obre les eines de desenvolupador: fes clic dret a la pàgina i tria Inspecciona, o prem F12 (Cmd+Opció+I en un Mac). Ves a la pestanya Consola i refresca la pàgina.

Mira el primer error en vermell; els següents sovint són efectes secundaris. El que diu indica la causa:

Copia el text complet de l’error, incloent-hi el nom del fitxer i el número de línia. Si fas servir un constructor amb IA, enganxa-ho directament al xat.

Pas 2: comprova que els fitxers s’han carregat

Obre la pestanya Xarxa, marca Desactiva la memòria cau i refresca. Mira les peticions dels fitxers .js i .css.

• Estat 404 en un fitxer JavaScript: la pàgina demana un fitxer que no és al servidor.
• Estat 200 però el tipus és text/html: el servidor ha retornat una pàgina (sovint el mateix index.html, per un fallback SPA) en lloc del script. La causa és la mateixa: el fitxer no és on la pàgina l’espera.

Motius habituals:

Ruta base incorrecta. Si l’app es serveix des d’una subcarpeta, com exemple.com/app/, però s’ha compilat per carregar fitxers des de /assets/..., cada petició de script falla. A Vite és l’opció base de vite.config; a Create React App és el camp homepage; a Next.js és basePath. Ha de coincidir amb el lloc on l’app es serveix realment.

index.html antic. Les eines de compilació posen als fitxers noms amb un hash de contingut, com index-a1b2c3.js. Després d’un nou desplegament, el fitxer antic desapareix. Si un navegador o una CDN encara té el index.html antic en memòria cau, demana el fitxer antic i no obté res. Un refresc forçat (Cmd+Maj+R o Ctrl+Maj+R) ho confirma. La solució a llarg termini és servir index.html amb una capçalera de memòria cau curta o inexistent, mentre els fitxers amb hash es guarden molt de temps.

La compilació no ha acabat o no s’ha desplegat. Si la compilació ha fallat, és possible que l’allotjament serveixi una carpeta de sortida antiga o buida. Revisa el registre de compilació per trobar errors.

S’ha publicat la carpeta equivocada. L’allotjament ha de servir la sortida de compilació (normalment dist o build), no la carpeta del codi font. Servir el codi font et dona un index.html que apunta a /src/main.tsx, que els navegadors no poden executar.

Pas 3: comprova les variables d’entorn

Les apps de front end sovint llegeixen configuracions com una URL d’API o una clau pública en el moment de la compilació. Si una variable falta a la compilació en directe, codi com createClient(undefined, undefined) falla immediatament i la pàgina es queda en blanc.

Coses a saber:

• A Vite, només les variables amb el prefix VITE_ estan disponibles al codi del navegador, i es llegeixen com import.meta.env.VITE_NAME. A Create React App és REACT_APP_; a Next.js, NEXT_PUBLIC_.
• Aquests valors es incorporen en el moment de la compilació. Afegir una variable després de compilar no fa res fins que tornes a compilar i a desplegar.
• La vista prèvia o la teva màquina local poden tenir un fitxer .env que la compilació de producció no té. Defineix les mateixes variables a l’allotjament.
• Tot el que té aquests prefixos acaba en el JavaScript públic. Posa-hi només valors públics, mai claus secretes.

Una prova ràpida: busca a l’error de la consola un undefined a prop del nom d’una configuració, o pregunta:

L’app publicada mostra una pàgina en blanc. Llista cada variable d’entorn que llegeix el front end, comprova quines falten o estan buides a la compilació en directe, i fes que l’app mostri un missatge d’error clar en lloc d’una pàgina en blanc quan en falti alguna.

Pas 4: arregla l’error

Si la consola mostra un error normal de JavaScript, el codi s’ha trencat durant el renderitzat. Causes habituals a les apps construïdes amb IA:

• Dades encara no carregades. Un component llegeix user.name abans que user hagi arribat. L’arranjament és un estat de càrrega, o l’encadenament opcional (user?.name).
• Dades buides. Un compte nou no té registres, i el codi dona per fet que la llista té almenys un element.
• Forma de dades inesperada. Una API ha retornat un objecte d’error en lloc de la llista que el codi esperava.
• Un import que falta després que un fitxer s’hagi reanomenat o mogut.
• Usar una API exclusiva del navegador durant el renderitzat al servidor, com window o localStorage en un component de servidor de Next.js.

Dona a la IA l’error complet, la pàgina i amb quin compte havies iniciat la sessió:

La pàgina del tauler està en blanc per als usuaris nous. Consola: TypeError: Cannot read properties of undefined (reading 'map') a ProjectList.tsx:18. Funciona per al meu compte, que té projectes. Arregla-ho perquè un compte buit mostri «Encara no hi ha projectes», i prova un compte nou a la vista prèvia.

Pas 5: afegeix un error boundary

A React, un component que falla pot desmuntar tota l’app, i per això un petit error produeix una pàgina completament en blanc. Un error boundary és un component que captura els errors de renderitzat de la part de sota i mostra un missatge alternatiu.

Afegeix un error boundary al voltant de les rutes principals que mostri «Alguna cosa ha fallat» amb un botó de Recarregar, i que registri l’error a la consola. Mantén la capçalera i la navegació fora del boundary perquè encara es renderitzin.

No arregla l’error, però els visitants veuen un missatge en lloc d’una pantalla en blanc, i tu veus on s’ha trencat.

Pas 6: sense errors, però encara en blanc

Si la consola està neta i els scripts es carreguen:

• Revisa la pestanya Elements. Hi ha contingut dins de <div id="root">? Si és així, es renderitza però és invisible: text blanc sobre fons blanc, opacity: 0, display: none, o un element a pantalla completa que ho tapa.
• Revisa el router. Si cap ruta coincideix amb la URL actual i no hi ha una ruta de «no trobat», alguns routers no renderitzen res. Afegeix una ruta comodí que mostri una pàgina 404.
• Revisa el punt de muntatge. El codi s’ha de muntar en un element que existeixi. Si index.html té id="app" i el codi busca root, no apareix res (i React normalment registra un error).
• Revisa una extensió del navegador. Prova una finestra privada. Els bloquejadors d’anuncis de vegades bloquegen scripts amb noms com analytics o ads.

En blanc només després de refrescar una pàgina?

Si la pàgina d’inici funciona però refrescar /dashboard mostra una pàgina en blanc o un 404, el servidor no sap que ha d’enviar index.html per a les rutes de l’app. És un problema de fallback d’encaminament, tractat a com arreglar els errors 404 després de publicar.

Errors habituals

• Llegir l’últim error en lloc del primer. La primera línia en vermell sol ser la causa.
• Definir variables d’entorn sense recompilar. Les variables del front end es fixen en el moment de la compilació.
• Provar només amb el teu propi compte. Els errors per comptes buits són una de les causes més habituals de pàgines en blanc.
• Suposar que el desplegament ha funcionat. Revisa el registre de compilació abans de depurar el codi.
• Culpar la memòria cau del navegador de tot. Un refresc forçat ho descarta en pocs segons; si la pàgina encara està en blanc, és una altra cosa.

Pàgines en blanc a Mythex

Si la Vista prèvia està en blanc, primer comprova que l’app s’està executant (obre Codi → terminal), després demana a Mythex que iniciï el servidor correcte, fes clic a Actualitza a la barra d’eines de la vista prèvia, o fes servir /fix. Per a una URL publicada en blanc, la documentació suggereix esperar un minut i fer un refresc forçat, confirmar que les variables d’entorn i la base de dades s’han configurat abans de publicar, i revisar la quota del teu allotjament. Recorda que una app publicada és una instantània: després d’arreglar alguna cosa, torna a publicar. Si un canvi ha causat el problema, Torna a aquest punt a l’última resposta correcta reverteix el projecte. Consulta Resolució de problemes i Resolució de problemes de publicació a la documentació, i la nostra guia general sobre com depurar una app construïda amb IA.

Llista de verificació de pàgina en blanc

• S’ha llegit el primer error en vermell a la Consola
• S’han revisat a la pestanya Xarxa els fitxers .js/.css que donen 404 o retornen HTML
• La ruta base coincideix amb el lloc on es serveix l’app
• La compilació ha acabat, i la carpeta de sortida és la que es publica
• Totes les variables d’entorn del front end estan definides a la compilació en directe, i després s’ha recompilat
• L’error s’ha arreglat, també per a comptes buits i nous
• Hi ha un error boundary perquè els errors futurs mostrin un missatge
• Hi ha una ruta comodí per a les URL desconegudes
• S’ha provat després d’un refresc forçat i en una finestra privada

Preguntes