Pagina bianca dopo il deploy: perché succede e come risolvere

Hai pubblicato la tua app, apri l'indirizzo e vedi solo una pagina bianca. Oppure la home funziona, ma ricaricando un'altra pagina compare un errore 404. Una pagina bianca dopo il deploy quasi sempre significa che il codice JavaScript dell'app non è riuscito a partire nel browser: mancano delle variabili, il server non trova i file giusti o non sa come gestire gli indirizzi interni. Non hai perso il lavoro, e nella maggior parte dei casi la causa si trova in pochi minuti guardando la console.

Perché vedi una pagina bianca e non un errore

Molte app create con Lovable, Bolt e strumenti simili sono «single page application» (SPA): il server invia una pagina HTML quasi vuota, con un solo contenitore, e poi è il JavaScript a disegnare tutto il resto nel browser. Il deploy, cioè la pubblicazione dell'app su un server raggiungibile da internet, mette online proprio quella pagina e quei file.

Immagina un teatro: il server apre il sipario, ma la scena la portano gli attori, cioè il JavaScript. Se gli attori non arrivano o inciampano all'ingresso, il pubblico vede un palco vuoto. Ecco la tua pagina bianca. Il messaggio d'errore c'è, ma non sulla pagina: è nella console del browser.

Le cause più comuni della pagina bianca dopo il deploy

Variabili d'ambiente mancanti

Le variabili d'ambiente sono impostazioni salvate fuori dal codice, come l'indirizzo del database o una chiave pubblica. In anteprima la piattaforma le fornisce in automatico; sull'hosting, cioè il servizio che tiene online l'app, spesso vanno inserite a mano. Se mancano, l'app si blocca all'avvio con messaggi come supabaseUrl is required. o con valori undefined.

Due dettagli importanti. Nelle app basate su Vite, lo strumento usato da molti di questi tool, le variabili da usare nel browser devono iniziare con VITE_. E vengono «incise» nei file durante la build, la fase in cui il codice viene preparato per la pubblicazione: se le aggiungi dopo, devi rifare il deploy. Trovi tutti i dettagli nella guida sulle variabili d'ambiente e le chiavi API.

File JavaScript non trovati

La pagina HTML dice al browser di caricare file come /assets/index-abc123.js. Se il percorso è sbagliato, per esempio perché l'app è pubblicata in una sottocartella e il «percorso base» (l'impostazione che dice all'app in quale cartella del sito vive) non è stato aggiornato, il browser non trova i file e non parte nulla. Nella console vedi richieste in errore 404 o questo messaggio:

Failed to load module script: Expected a JavaScript module script
but the server responded with a MIME type of "text/html".

Tradotto: il browser ha chiesto un file JavaScript e il server gli ha risposto con una pagina HTML, di solito perché il file non esiste a quell'indirizzo.

Routing non configurato: 404 quando ricarichi

In una SPA gli indirizzi come /dashboard o /profilo esistono solo dentro l'app, non come file sul server. Se arrivi dalla home e clicchi, tutto funziona. Se ricarichi la pagina o apri il link direttamente, il server cerca un file /dashboard, non lo trova e risponde 404.

La soluzione è dire all'hosting: «per qualsiasi indirizzo, servi index.html e lascia decidere all'app». Su Netlify si fa con un file _redirects nella cartella pubblicata (nei progetti Vite si mette nella cartella public, che viene copiata nella build):

/*    /index.html   200

Su Vercel, con un file vercel.json nella cartella principale del progetto:

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Altri hosting hanno un'opzione equivalente, spesso chiamata «SPA» o «riscrittura verso index.html».

Un errore JavaScript che in anteprima non c'era

A volte l'app parte, ma va in crash appena carica i dati. Un classico è TypeError: Cannot read properties of undefined (reading 'map'): il codice si aspettava una lista e non ha ricevuto niente. Online succede più spesso perché il database di produzione è vuoto, ha dati diversi o regole di accesso più severe. Se l'AI ha già provato più volte a correggerlo senza successo, leggi anche cosa fare quando l'AI continua a rompere il codice.

Cartella di pubblicazione o build sbagliata

Se l'hosting pubblica la cartella sbagliata, per esempio quella del codice sorgente invece di dist (la cartella che la build produce), vedi una pagina vuota o un elenco di file. Se invece la build fallisce, alcune piattaforme lasciano online la versione precedente, altre non pubblicano nulla. Come leggere il log di una build fallita lo spieghiamo nella guida sull'errore «build failed» nel deploy.

Cache dopo un aggiornamento

Dopo un nuovo deploy il browser può tenere in memoria una vecchia versione della pagina, che punta a file non più esistenti. Il risultato è una pagina bianca solo per alcuni utenti. Un ricaricamento forzato o una finestra in incognito di solito lo confermano.

Come capire qual è il tuo caso

1. Apri il sito, premi F12 e vai nella scheda «Console». Il primo errore in rosso è quasi sempre l'indizio giusto.
2. Vai nella scheda «Network» (Rete), ricarica e cerca richieste in rosso: file .js o .css con errore 404 indicano un problema di percorsi.
3. Prova a ricaricare una pagina interna, non la home. Se solo quella dà 404, è il routing.
4. Apri il sito in una finestra in incognito per escludere la cache.
5. Guarda il sorgente della pagina (tasto destro e «Visualizza sorgente pagina»). Se vedi un HTML corto con un contenitore vuoto e qualche riga <script>, il server sta inviando la pagina giusta e il problema è nel JavaScript. Se invece vedi la pagina di errore dell'hosting, il problema è nella pubblicazione o nel routing.

Cosa puoi fare tu

1. Copia l'errore esatto dalla console e conservalo: ti servirà per capire, o per chiedere all'AI una correzione mirata.
2. Confronta le variabili d'ambiente dell'anteprima con quelle dell'hosting, nome per nome. Poi rifai il deploy.
3. Aggiungi la regola per il routing se il problema è il 404 al refresh. È un file di poche righe, come negli esempi sopra.
4. Verifica le impostazioni di build nell'hosting: comando di build e cartella di pubblicazione devono corrispondere a quelli del progetto.
5. Chiedi all'AI una correzione circoscritta, incollando l'errore e specificando che il problema compare solo online.

Come evitare che si ripeta

Prima di ogni nuova pubblicazione bastano pochi controlli: le variabili d'ambiente sono tutte presenti sull'hosting? Il file per il routing è ancora nel progetto? Dopo il deploy, apri il sito in incognito, ricarica almeno una pagina interna e dai un'occhiata alla console. Sono due minuti che ti evitano di scoprire il problema dai tuoi utenti.

Se l'app funziona in anteprima e online no per motivi diversi da quelli elencati, trovi altri casi nella guida sulle app che funzionano in anteprima ma non online.

Quando conviene farti aiutare

Se la console mostra errori che non riesci a interpretare, se le correzioni dell'AI peggiorano la situazione o se l'app ha già utenti che trovano una pagina vuota, conviene far controllare il deploy a qualcuno che lo fa tutti i giorni. Spesso il problema è una sola impostazione, ma trovarla alla cieca può richiedere ore.

Di solito partiamo dalla console e dalle impostazioni dell'hosting, sistemiamo la causa e verifichiamo che anche le pagine interne e i ricaricamenti funzionino. Se vuoi una mano, prenota una call gratuita: in 20 minuti capiamo insieme da dove viene la tua pagina bianca.