Come risolvere gli errori 404 dopo il deploy di un sito o di un'app

Se la tua app funziona in locale ma le pagine danno 404 dopo il deploy, la causa più comune è la mancanza del routing per app a pagina singola (SPA): il server cerca un file chiamato /dashboard che non esiste, perché quella rotta esiste solo in JavaScript. La soluzione è una regola di fallback che serve index.html per le rotte dell'app. Altre cause sono file mancanti nell'output di build, percorsi case-sensitive, differenze negli slash finali, un base path errato e route API mai distribuite.

Inizia annotando esattamente quale URL dà 404 e come ci sei arrivato. Il modello indica subito la causa.

Passo 1: individua il modello

Per vedere il vero codice di stato, apri gli strumenti per sviluppatori (clic destro → Ispeziona), vai alla scheda Rete (Network), ricarica e guarda lo stato della prima richiesta.

Passo 2: aggiungi il fallback SPA

È il caso classico. In un'app a pagina singola con React, Vue o Svelte, il server ha solo pochi file reali: index.html e alcuni file JavaScript e CSS. Le rotte come /dashboard o /projects/42 sono gestite da un router nel browser.

• Cliccare un link funziona: il router cambia l'URL e disegna la nuova pagina senza chiedere nulla al server.
• Ricaricare o aprire un link direttamente fallisce: il browser chiede al server /dashboard, il server non ha quel file e risponde 404.

La soluzione è una regola che dice: se la richiesta non corrisponde a un file reale, servi index.html con stato 200 e lascia il controllo al router. Come la aggiungi dipende dall'host (controlla la documentazione attuale del tuo host, perché i dettagli cambiano):

Assicurati che la regola non inghiotta i file reali: le richieste per /assets/app.js devono ancora restituire il file JavaScript. Se restituiscono index.html, ottieni una pagina bianca con l'errore "Failed to load module script". Vedi come risolvere una pagina bianca.

Dai anche al router una rotta catch-all, così gli URL che non corrispondono a nessuna pagina mostrano un messaggio "Pagina non trovata" gentile invece di niente.

Se non puoi cambiare le impostazioni del server, il routing con hash (URL come /#/dashboard) evita il problema, perché la parte dopo # non viene mai inviata al server. È un ripiego, non la prima scelta: gli URL sono meno belli e meno amichevoli per i motori di ricerca.

I framework che generano le pagine sul server o al momento della build (Next.js, Astro e simili) di solito hanno file reali o route server per ogni pagina, quindi questo problema è meno comune lì. Il loro equivalente è una pagina che non è stata generata al momento della build.

Passo 3: verifica cosa è stato davvero distribuito

Se tutto dà 404, probabilmente il server non sta servendo la tua app compilata.

• La cartella giusta. L'host deve pubblicare l'output di build (di solito dist per Vite, build per Create React App, out per un export statico di Next.js), non la radice del progetto.
• La build è andata a buon fine. Leggi il log del deploy. Se la build è fallita, l'host potrebbe non aver distribuito nulla, o una versione vecchia.
• index.html è al livello principale della cartella pubblicata, non in una sottocartella.
• Il base path corrisponde. Se l'app è servita da esempio.com/app/, deve essere compilata con quel base (l'opzione base di Vite, basename di React Router), altrimenti ogni rotta e ogni asset mancano.

Passo 4: correggi file mancanti e percorsi errati

Quando le pagine si caricano ma gli asset danno 404:

• Maiuscole e minuscole. macOS e Windows di solito trattano Logo.png e logo.png come lo stesso file. La maggior parte dei server Linux no. Fai corrispondere ogni riferimento al nome esatto del file.
• File fuori dalla build. In Vite, i file in public/ vengono copiati così come sono e referenziati dalla radice (/logo.png). I file importati nel codice vengono inclusi nel bundle. Un file collocato altrove nel progetto potrebbe non essere distribuito affatto.
• Percorsi relativi. images/photo.jpg viene risolto relativamente all'URL corrente, quindi si rompe su /blog/post-1. Usa /images/photo.jpg.
• File caricati salvati sul disco locale. Se i caricamenti degli utenti sono stati scritti nella cartella del server, scompaiono quando si distribuisce una nuova versione. Usa un archivio file adeguato.

Passo 5: gestisci in modo coerente gli slash finali

/about e /about/ sono URL diversi. Gli host differiscono nel fatto di aggiungere o rimuovere lo slash, e una mancata corrispondenza con i tuoi link o con il router può produrre 404 o cicli di redirect. Scegli uno stile, fai in modo che i link lo usino, e configura l'host per reindirizzare l'altra forma verso di esso. La coerenza aiuta anche i motori di ricerca, che altrimenti potrebbero vedere due copie di ogni pagina.

Passo 6: correggi le route API che danno 404

Se la pagina si carica ma la scheda Rete mostra richieste /api/... con 404:

• Il back end non è distribuito. Un host statico serve solo file; un back end deve girare da qualche parte.
• Il percorso è instradato in modo diverso in produzione. In sviluppo, un proxy può aver inoltrato /api a un server separato. In produzione, l'host ha bisogno di una rewrite equivalente, oppure il front end deve chiamare l'indirizzo reale dell'API.
• Il fallback SPA ha catturato la richiesta. Una richiesta API che restituisce index.html con stato 200 significa che la regola di fallback è troppo ampia. Escludi /api/* da essa.

Le richieste dell'app pubblicata a /api/orders danno 404, ma nell'anteprima funzionano. Controlla come viene instradato /api nell'anteprima e nell'app pubblicata, e fai in modo che il front end pubblicato raggiunga il back end nello stesso modo.

Passo 7: reindirizza i vecchi URL

Se hai cambiato piattaforma o ristrutturato il sito, i vecchi URL ancora usati da persone e motori di ricerca daranno 404. Aggiungi un redirect 301 (permanente) da ogni vecchio URL alla sua nuova posizione. Tieni un elenco e verificane un campione dopo il lancio. La nostra guida su come migrare un sito WordPress spiega come costruire quell'elenco.

Passo 8: verifica il dominio

Se l'app funziona all'indirizzo dell'host ma dà 404 sul tuo dominio personalizzato, il dominio potrebbe puntare al progetto sbagliato, oppure l'host potrebbe non avere ancora collegato il dominio al tuo sito. Controlla i record DNS e le impostazioni dei domini dell'host. Vedi come collegare un dominio personalizzato.

Rendi utile la pagina 404 reale

Alcuni 404 sono corretti: qualcuno ha digitato male un URL. Rendi quella pagina utile:

• Un breve messaggio e un link alla home e alle sezioni principali
• Una casella di ricerca, se il sito ha la ricerca
• La stessa intestazione e la stessa navigazione del resto del sito

Dove la tua configurazione lo consente, restituisci un codice di stato 404 reale per le pagine che non esistono. Un messaggio "non trovato" restituito con stato 200 è ciò che i motori di ricerca chiamano soft 404, e può sprecare il loro tempo di scansione e confondere l'indicizzazione.

Errori comuni

• Testare solo cliccando. Verifica sempre incollando URL profondi in una nuova scheda e ricaricando.
• Un fallback che cattura tutto. Asset e route API restituiscono index.html, causando pagine bianche ed errori API confusi.
• Maiuscole e minuscole non corrispondenti che si rompono solo sul server.
• Distribuire la cartella dei sorgenti invece dell'output di build.
• Ristrutturare gli URL senza redirect. Ogni vecchio link diventa un 404.

I 404 in Mythex

In Mythex pubblichi dallo spazio di lavoro, e i front end statici vengono distribuiti come siti statici. Se una pagina pubblicata dà 404, fornisci all'agente l'URL esatto, dicendo se succede al ricaricamento o al clic, e cosa mostra la scheda Rete, poi chiedigli di controllare il routing. Ripubblica dopo la correzione, perché l'app live è uno snapshot finché non ripubblichi. Se di recente hai cambiato il progetto e il sito live sembra vecchio, ripubblica e ricarica forzatamente la pagina. Usa Fix with AI nella finestra di pubblicazione se la build fallisce. Vedi Come pubblicare e Risoluzione dei problemi di pubblicazione nella documentazione, e la nostra guida su come fare debug di un'app creata con l'AI.

Checklist per i 404

• Annotato esattamente quali URL danno 404, e se al clic, al ricaricamento o a entrambi
• Il fallback SPA serve index.html per le rotte dell'app, con stato 200
• Il fallback esclude i file reali e /api/*
• Il router ha una rotta catch-all "non trovato"
• La cartella dell'output di build è quella pubblicata, e la build è riuscita
• Il base path corrisponde a dove l'app è servita
• Le maiuscole dei nomi dei file corrispondono a ogni riferimento
• I percorsi degli asset iniziano con /
• Stile degli slash finali coerente
• Route API distribuite e instradate in produzione
• Redirect 301 per i vecchi URL
• Link profondi testati incollandoli in una nuova scheda

Domande