Come risolvere una pagina bianca nella tua app web

Una pagina bianca significa quasi sempre una di due cose: il JavaScript dell'app è andato in crash prima di disegnare qualcosa, oppure il JavaScript non si è mai caricato. Apri la console del browser (clic destro → Ispeziona → Console) e leggi il primo errore rosso, poi controlla la scheda Rete per i file che non si sono caricati. Le cause più comuni sono una variabile d'ambiente mancante, un base path errato, una build non terminata o un crash in un componente.

Questa guida copre le app a pagina singola costruite con React, Vue o framework simili (incluse le app create dai builder AI), che è dove le pagine bianche sono più frequenti.

Perché la pagina è bianca

Una moderna app a pagina singola (SPA) invia al browser un file HTML quasi vuoto, più o meno così:

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

Poi il JavaScript costruisce tutta la pagina dentro quel div vuoto. Se lo script non si carica, o lancia un errore prima di renderizzare, il div resta vuoto e vedi il bianco. La pagina non è "rotta" in modo visibile; semplicemente non è mai stata disegnata.

Per questo la correzione inizia sempre dagli strumenti per sviluppatori, non dalla pagina stessa.

Passo 1: leggi la console

Apri gli strumenti per sviluppatori: clic destro sulla pagina e scegli Ispeziona, oppure premi F12 (Cmd+Opzione+I su Mac). Vai alla scheda Console e ricarica la pagina.

Guarda il primo errore rosso; quelli successivi sono spesso effetti collaterali. Ciò che dice indica la causa:

Copia il testo completo dell'errore, incluso il nome del file e il numero di riga. Se usi un builder AI, incollalo direttamente nella chat.

Passo 2: verifica che i file si siano caricati

Apri la scheda Rete, spunta Disabilita cache e ricarica. Guarda le richieste per i file .js e .css.

• Stato 404 su un file JavaScript: la pagina chiede un file che non è sul server.
• Stato 200 ma tipo text/html: il server ha restituito una pagina (spesso index.html stesso, per via di un fallback SPA) invece dello script. Stessa causa: il file non è dove la pagina se lo aspetta.

Cause comuni:

Base path errato. Se l'app è servita da una sottocartella, come esempio.com/app/, ma è stata compilata per caricare i file da /assets/..., ogni richiesta di script fallisce. In Vite è l'opzione base in vite.config; in Create React App è il campo homepage; in Next.js è basePath. Deve corrispondere a dove l'app è effettivamente servita.

index.html obsoleto. Gli strumenti di build assegnano ai file nomi con un hash del contenuto, come index-a1b2c3.js. Dopo un nuovo deploy, il vecchio file scompare. Se un browser o una CDN ha ancora in cache il vecchio index.html, richiede il vecchio file e non ottiene nulla. Un aggiornamento forzato (Cmd+Maiusc+R o Ctrl+Maiusc+R) lo conferma. La soluzione a lungo termine è servire index.html con un'intestazione di cache breve o assente, mentre i file con hash restano in cache a lungo.

La build non è terminata o non è stata distribuita. Se la build è fallita, l'host potrebbe servire una cartella di output vecchia o vuota. Controlla il log di build per gli errori.

È stata pubblicata la cartella sbagliata. L'host deve servire l'output di build (di solito dist o build), non la cartella dei sorgenti del progetto. Servire i sorgenti ti dà un index.html che punta a /src/main.tsx, che i browser non possono eseguire.

Passo 3: controlla le variabili d'ambiente

Le app front end spesso leggono impostazioni come un URL API o una chiave pubblica al momento della build. Se una variabile manca nella build live, codice come createClient(undefined, undefined) va in errore subito, e la pagina diventa bianca.

Cose da sapere:

• In Vite, solo le variabili con prefisso VITE_ sono disponibili nel codice del browser, lette come import.meta.env.VITE_NOME. In Create React App è REACT_APP_; in Next.js, NEXT_PUBLIC_.
• Questi valori vengono incorporati al momento della build. Aggiungere una variabile dopo la build non serve a nulla finché non ricompili e ridistribuisci.
• La macchina locale o l'anteprima possono avere un file .env che la build di produzione non ha. Imposta le stesse variabili sull'host.
• Tutto ciò che ha questi prefissi finisce nel JavaScript pubblico. Metti lì solo valori pubblici, mai chiavi segrete.

Un test rapido: cerca nell'errore di console undefined vicino al nome di un'impostazione, oppure chiedi:

La pagina pubblicata mostra una pagina bianca. Elenca ogni variabile d'ambiente che il front end legge, controlla quali sono mancanti o vuote nella build live, e fai in modo che l'app mostri un messaggio d'errore chiaro invece di una pagina bianca quando ne manca una.

Passo 4: correggi il crash

Se la console mostra un normale errore JavaScript, il codice è andato in crash durante il rendering. Cause tipiche nelle app create con l'AI:

• Dati non ancora caricati. Un componente legge user.name prima che user sia arrivato. La correzione è uno stato di caricamento, oppure l'optional chaining (user?.name).
• Dati vuoti. Un account nuovo non ha record, e il codice presume che la lista abbia almeno un elemento.
• Forma dei dati inattesa. Un'API ha restituito un oggetto d'errore invece della lista che il codice si aspettava.
• Un import mancante dopo che un file è stato rinominato o spostato.
• Uso di un'API solo browser durante il rendering lato server, come window o localStorage in un server component di Next.js.

Passa all'AI l'errore completo, la pagina in cui ti trovi e con quale account eri connesso:

La pagina Dashboard è vuota per i nuovi utenti. Console: TypeError: Cannot read properties of undefined (reading 'map') in ProjectList.tsx:18. Funziona per il mio account, che ha dei progetti. Correggila in modo che un account vuoto mostri "Nessun progetto ancora", e verifica un account nuovo nell'anteprima.

Passo 5: aggiungi un error boundary

In React, un solo componente che va in crash può smontare l'intera app, ed è per questo che un piccolo bug produce una pagina completamente bianca. Un error boundary è un componente che intercetta gli errori di rendering sotto di sé e mostra un ripiego invece.

Aggiungi un error boundary attorno alle rotte principali che mostri "Qualcosa è andato storto" con un pulsante Ricarica, e registri l'errore in console. Tieni l'intestazione e la navigazione fuori da esso, così continuano a essere visibili.

Non risolve il bug, ma i visitatori vedono un messaggio invece di una schermata bianca, e tu vedi dove si è rotto.

Passo 6: nessun errore, ma è comunque bianca

Se la console è pulita e gli script si caricano:

• Controlla la scheda Elementi. C'è contenuto dentro <div id="root">? Se sì, sta renderizzando ma è invisibile: testo bianco su bianco, opacity: 0, display: none, oppure un elemento a schermo intero che lo copre.
• Controlla il router. Se nessuna rotta corrisponde all'URL corrente e non c'è una rotta "non trovato", alcuni router non renderizzano nulla. Aggiungi una rotta catch-all che mostri una pagina 404.
• Controlla il punto di montaggio. Il codice deve montarsi in un elemento che esiste. Se index.html ha id="app" e il codice cerca root, non appare nulla (e React di solito registra un errore).
• Controlla le estensioni del browser. Prova una finestra in incognito. I blocchi pubblicitari a volte bloccano script con nomi come analytics o ads.

Bianca solo dopo aver ricaricato una pagina?

Se la home funziona ma ricaricando /dashboard vedi una pagina bianca o un 404, il server non sa che deve inviare index.html per le rotte dell'app. È un problema di fallback del routing, trattato in come risolvere gli errori 404 dopo il deploy.

Errori comuni

• Leggere l'ultimo errore invece del primo. La prima riga rossa è di solito la causa.
• Impostare le variabili d'ambiente senza ricompilare. Le variabili del front end sono fissate al momento della build.
• Testare solo con il tuo account. I crash con account vuoti sono una delle cause più comuni di pagina bianca.
• Dare per scontato che il deploy sia riuscito. Controlla il log di build prima di fare debug del codice.
• Dare la colpa alla cache del browser per tutto. Un aggiornamento forzato la esclude in pochi secondi; se la pagina resta bianca, il problema è altrove.

Pagine bianche in Mythex

Se l'anteprima è bianca, prima verifica che l'app sia in esecuzione (apri Code → terminal), poi chiedi a Mythex di avviare il server corretto, clicca Refresh nella barra degli strumenti dell'anteprima, oppure usa /fix. Per un URL pubblicato bianco, la documentazione suggerisce di attendere un minuto e aggiornare forzatamente, confermare che le variabili d'ambiente e il database siano stati configurati prima della pubblicazione, e controllare il tuo limite di hosting. Ricorda che un'app pubblicata è uno snapshot: dopo una correzione, ripubblica. Se una modifica ha causato il problema, Torna a questo punto sull'ultima risposta buona riporta il progetto indietro. Vedi Risoluzione dei problemi e Risoluzione dei problemi di pubblicazione nella documentazione, e la nostra guida generale su come fare debug di un'app creata con l'AI.

Checklist per la pagina bianca

• Letto il primo errore rosso nella Console
• Controllata la scheda Rete per i file .js/.css che danno 404 o restituiscono HTML
• Il base path corrisponde a dove l'app è servita
• Build terminata, e la cartella di output è quella pubblicata
• Tutte le variabili d'ambiente del front end impostate sulla build live, poi ricompilato
• Crash corretto, anche per account vuoti e nuovi
• Error boundary attivo, così i crash futuri mostrano un messaggio
• Rotta catch-all per gli URL sconosciuti
• Testato dopo un aggiornamento forzato e in una finestra in incognito

Domande