Cum repari erorile 404 după publicarea site-ului sau aplicației

Dacă aplicația ta funcționează local, dar paginile returnează 404 după publicare, cauza cea mai frecventă este lipsa rutării single-page application (SPA): serverul caută un fișier numit /dashboard care nu există, pentru că ruta există doar în JavaScript. Soluția este o regulă de rezervă care servește index.html pentru rutele aplicației. Alte cauze sunt fișierele lipsă din rezultatul build-ului, căile sensibile la majuscule, diferențele de slash final, o cale de bază (base path) greșită și rute API care nu au fost niciodată publicate.

Începe prin a nota exact ce URL dă 404 și cum ai ajuns acolo. Tiparul indică direct cauza.

Pasul 1: Găsește tiparul

Ca să vezi codul real de status, deschide uneltele de dezvoltator (click dreapta → Inspect), mergi la tab-ul Network, reîncarcă pagina și uită-te la statusul primei cereri.

Pasul 2: Adaugă rezerva SPA

Acesta este cazul clasic. Într-o aplicație single-page în React, Vue sau Svelte, serverul are doar câteva fișiere reale: index.html și niște JavaScript și CSS. Rute precum /dashboard sau /projects/42 sunt gestionate de un router în browser.

• Click-ul pe un link funcționează: routerul schimbă URL-ul și desenează pagina nouă fără să ceară serverului.
• Refresh-ul sau deschiderea directă a unui link eșuează: browserul cere serverului /dashboard, serverul nu are un asemenea fișier și returnează 404.

Soluția este o regulă care spune: dacă cererea nu corespunde unui fișier real, servește index.html cu status 200 și lasă routerul să preia controlul. Cum o adaugi depinde de host (verifică documentația actuală a hostului tău, pentru că detaliile se schimbă):

Asigură-te că regula nu înghite fișierele reale: cererile pentru /assets/app.js trebuie să returneze în continuare fișierul JavaScript. Dacă returnează index.html, vei avea o pagină albă cu eroarea „Failed to load module script”. Vezi cum repari o pagină albă.

De asemenea, dă routerului o rută catch-all, ca adresele care nu corespund niciunei pagini să afișeze o pagină prietenoasă „Pagina nu a fost găsită”, în loc de nimic.

Dacă nu poți schimba setările serverului, rutarea prin hash (URL-uri ca /#/dashboard) evită problema, pentru că partea de după # nu este trimisă niciodată serverului. Este o soluție de compromis, nu prima alegere: URL-urile sunt mai urâte și mai greu de înțeles pentru motoarele de căutare.

Frameworkurile care randează paginile pe server sau le generează la build (Next.js, Astro și similare) au de obicei fișiere reale sau rute de server pentru fiecare pagină, deci această problemă este mai rară acolo. Echivalentul lor este o pagină care nu a fost generată la build.

Pasul 3: Verifică ce s-a implementat efectiv

Dacă totul dă 404, probabil serverul nu servește aplicația ta construită.

• Folderul corect. Hostul trebuie să publice rezultatul build-ului (de obicei dist pentru Vite, build pentru Create React App, out pentru un export static Next.js), nu rădăcina proiectului.
• Build-ul a rulat. Citește jurnalul de deploy. Dacă build-ul a eșuat, hostul poate să nu fi implementat nimic sau să fi implementat o versiune veche.
• index.html este la nivelul de sus al folderului publicat, nu într-un subfolder.
• Calea de bază se potrivește. Dacă aplicația este servită din exemplu.ro/app/, trebuie construită cu acea bază (base în Vite, basename în React Router), altfel fiecare rută și fiecare resursă ratează.

Pasul 4: Repară fișierele lipsă și căile greșite

Când paginile se încarcă, dar resursele dau 404:

• Sensibilitatea la majuscule. macOS și Windows tratează de obicei Logo.png și logo.png ca același fișier. Majoritatea serverelor Linux nu. Fă ca fiecare referință să corespundă exact numelui fișierului real.
• Fișiere în afara build-ului. În Vite, fișierele din public/ sunt copiate ca atare și referite din rădăcină (/logo.png). Fișierele importate în cod sunt incluse în bundle. Un fișier care stă în altă parte a proiectului s-ar putea să nu fie implementat deloc.
• Căi relative. images/photo.jpg se rezolvă relativ la URL-ul curent, deci se strică pe /blog/post-1. Folosește /images/photo.jpg.
• Fișiere încărcate salvate pe discul local. Dacă încărcările utilizatorilor au fost scrise în folderul serverului, dispar când se implementează o versiune nouă. Folosește o stocare de fișiere adecvată.

Pasul 5: Gestionează consecvent slash-urile finale

/about și /about/ sunt URL-uri diferite. Hosturile diferă în privința adăugării sau eliminării slash-ului, iar o nepotrivire cu linkurile tale sau cu routerul poate produce 404-uri sau bucle de redirect. Alege un stil, fă linkurile să îl folosească și configurează hostul să redirecționeze cealaltă formă către el. Consecvența ajută și motoarele de căutare, care altfel pot vedea două copii ale fiecărei pagini.

Pasul 6: Repară rutele API care dau 404

Dacă pagina se încarcă, dar în tab-ul Network cererile /api/... returnează 404:

• Back-end-ul nu este implementat. Un host static servește doar fișiere; un back-end trebuie să ruleze undeva.
• Calea este rutată diferit în producție. În dezvoltare, un proxy poate fi trimis /api către un server separat. În producție, hostul are nevoie de un rewrite echivalent, sau front-end-ul trebuie să apeleze adresa reală a API-ului.
• Rezerva SPA a prins cererea. O cerere API care returnează index.html cu status 200 înseamnă că regula de rezervă este prea largă. Exclude /api/* din ea.

Cererile aplicației publicate către /api/orders returnează 404, deși funcționează în previzualizare. Verifică cum este rutat /api în previzualizare față de aplicația publicată și fă ca front-end-ul publicat să ajungă la back-end în același mod.

Pasul 7: Redirecționează URL-urile vechi

Dacă ai mutat lucrurile de pe alt site sau ai restructurat, URL-urile vechi pe care oamenii și motoarele de căutare le mai folosesc vor da 404. Adaugă un redirect 301 (permanent) de la fiecare URL vechi către noua lui adresă. Ține o listă și testează un eșantion după lansare. Ghidul nostru despre migrarea unui site WordPress acoperă construirea acelei liste.

Pasul 8: Verifică domeniul

Dacă aplicația funcționează la adresa hostului, dar dă 404 pe domeniul tău personalizat, este posibil ca domeniul să indice spre un alt proiect, sau hostul să nu aibă încă domeniul atașat site-ului tău. Verifică înregistrările DNS și setările de domeniu ale hostului. Vezi cum conectezi un domeniu personalizat.

Fă pagina ta reală de 404 utilă

Unele 404-uri sunt corecte: cineva a greșit un URL. Fă pagina aceea utilă:

• Un mesaj scurt și un link către pagina de start și secțiunile principale
• O casetă de căutare, dacă site-ul are căutare
• Același antet și aceeași navigare ca restul site-ului

Acolo unde configurația îți permite, returnează un status 404 real pentru paginile care nu există. Un mesaj „nu a fost găsit” returnat cu status 200 este ceea ce motoarele de căutare numesc soft 404, și poate irosi timpul lor de crawl și încurca indexarea.

Greșeli frecvente

• Testarea doar prin click. Testează întotdeauna lipind adrese adânci într-un tab nou și dând refresh.
• O rezervă care prinde totul. Resursele și rutele API returnează index.html, ceea ce produce pagini albe și erori API confuze.
• Majuscule nepotrivite care se strică doar pe server.
• Implementarea folderului sursă în loc de rezultatul build-ului.
• Restructurarea URL-urilor fără redirecturi. Fiecare link vechi devine un 404.

404-uri în Mythex

În Mythex publici din spațiul de lucru, iar front-end-urile statice se implementează ca site-uri statice. Dacă o pagină publicată dă 404, dă agentului URL-ul exact, spune dacă apare la refresh sau la click și ce arată tab-ul Network, apoi cere-i să verifice rutarea. Publică din nou după reparație, pentru că aplicația live este un instantaneu până când republici. Dacă ai schimbat recent proiectul și site-ul live pare vechi, publică din nou și fă hard refresh. Folosește Fix with AI din dialogul de publicare dacă build-ul eșuează. Vezi Cum publici și Depanarea publicării în documentație și ghidul nostru despre cum depanezi o aplicație construită cu AI.

Lista de verificare pentru 404

• Am notat exact ce URL-uri dau 404 și dacă la click, la refresh sau la ambele
• Rezerva SPA servește index.html pentru rutele aplicației, cu status 200
• Rezerva exclude fișierele reale și /api/*
• Routerul are o rută catch-all pentru „nu a fost găsit”
• Folderul de rezultat al build-ului este cel publicat, iar build-ul a reușit
• Calea de bază se potrivește cu locul unde este servită aplicația
• Capitalizarea numelor de fișiere se potrivește cu fiecare referință
• Căile resurselor încep cu /
• Stilul slash-ului final este consecvent
• Rutele API sunt implementate și rutate în producție
• Redirecturi 301 pentru URL-urile vechi
• Deep links testate lipindu-le într-un tab nou

Întrebări