Jak naprawić błędy 404 po wdrożeniu strony lub aplikacji
Jeśli aplikacja działa lokalnie, a po wdrożeniu strony zwracają 404, najczęstszą przyczyną jest brak routingu aplikacji jednostronicowej (SPA): serwer szuka pliku o nazwie /dashboard, który nie istnieje, bo ta trasa istnieje tylko w JavaScripcie. Rozwiązaniem jest reguła, która zwraca index.html dla tras aplikacji. Inne przyczyny to brakujące pliki w wyniku builda, ścieżki z rozróżnieniem wielkości liter, różnice w końcowym ukośniku, błędna ścieżka bazowa oraz trasy API, które nigdy nie zostały wdrożone.
Zacznij od zanotowania, który dokładnie adres daje 404 i jak tam trafiłeś. Wzorzec od razu wskazuje przyczynę.
Krok 1: Znajdź wzorzec
| Co widzisz | Najbardziej prawdopodobna przyczyna | Przejdź do |
|---|---|---|
| Strona główna działa; kliknięcia w linki działają; odświeżenie lub otwarcie głębokiego linku daje 404 | Brak fallbacku SPA | Krok 2 |
| Każda strona daje 404, także strona główna | Opublikowano zły folder albo build się nie wdrożył | Krok 3 |
| Strony się ładują, ale obrazy, czcionki lub skrypty dają 404 | Brakujące pliki w buildzie lub złe ścieżki | Krok 4 |
Działa z /about/, nie działa z /about (lub odwrotnie) | Obsługa końcowego ukośnika | Krok 5 |
/About nie działa, ale /about działa | Serwer rozróżnia wielkość liter | Krok 4 |
Strona się ładuje, ale wywołania danych do /api/... dają 404 | API niewdrożone lub niepodłączone do routingu | Krok 6 |
| Stare adresy z poprzedniej strony dają 404 | Brakujące przekierowania | Krok 7 |
| Tylko na własnej domenie | Konfiguracja DNS lub domeny | Krok 8 |
Aby zobaczyć rzeczywisty kod statusu, otwórz narzędzia deweloperskie (prawy przycisk → Zbadaj), przejdź do zakładki Sieć (Network), przeładuj stronę i sprawdź status pierwszego żądania.
Krok 2: Dodaj fallback SPA
To klasyczny przypadek. W aplikacji jednostronicowej w React, Vue lub Svelte serwer ma tylko kilka prawdziwych plików: index.html oraz trochę JavaScriptu i CSS. Trasy takie jak /dashboard czy /projects/42 obsługuje router w przeglądarce.
- Kliknięcie linku działa: router zmienia adres i rysuje nową stronę bez pytania serwera.
- Odświeżenie lub otwarcie linku bezpośrednio nie działa: przeglądarka pyta serwer o
/dashboard, serwer nie ma takiego pliku i zwraca 404.
Rozwiązaniem jest reguła mówiąca: jeśli żądanie nie pasuje do prawdziwego pliku, zwróć index.html ze statusem 200 i pozwól routerowi przejąć sterowanie. Sposób dodania zależy od hosta (sprawdź aktualną dokumentację, bo szczegóły się zmieniają):
| Host | Typowa reguła fallbacku |
|---|---|
| Netlify | Plik _redirects w opublikowanym folderze z regułą /* /index.html 200 |
| Vercel | Rewrite w vercel.json z wszystkich ścieżek do /index.html (presety frameworków często robią to same) |
| Cloudflare Pages | Domyślnie obsługuje fallback w stylu SPA, gdy nie ma 404.html w katalogu głównym |
| Nginx | try_files $uri $uri/ /index.html; w bloku location / |
| Apache | Reguła rewrite w .htaccess kierująca żądania nieistniejących plików do index.html |
| GitHub Pages | Brak przepisywania po stronie serwera; częste obejścia to routing oparty na hashu albo 404.html przekierowujące |
Upewnij się, że reguła nie połyka prawdziwych plików: żądania do /assets/app.js muszą nadal zwracać plik JavaScript. Jeśli zwracają index.html, dostajesz pustą stronę z błędem "Failed to load module script". Zobacz jak naprawić pustą białą stronę.
Daj też routerowi trasę przechwytującą wszystko, żeby adresy, które nie pasują do żadnej strony, pokazywały przyjazne "Nie znaleziono strony" zamiast niczego.
Jeśli nie możesz zmienić ustawień serwera, routing hashowy (adresy typu /#/dashboard) omija problem, bo część po # nigdy nie trafia do serwera. To obejście, a nie pierwszy wybór: adresy są brzydsze i mniej przyjazne dla wyszukiwarek.
Frameworki, które renderują strony po stronie serwera lub generują je podczas builda (Next.js, Astro i podobne), zwykle mają prawdziwe pliki lub trasy serwerowe dla każdej strony, więc ten konkretny problem zdarza się tam rzadziej. Ich odpowiednikiem jest strona, która nie została wygenerowana podczas builda.
Krok 3: Sprawdź, co faktycznie wdrożono
Jeśli wszystko daje 404, serwer prawdopodobnie nie serwuje zbudowanej aplikacji.
- Właściwy folder. Host musi publikować wynik builda (zwykle
distdla Vite,builddla Create React App,outdla statycznego eksportu Next.js), a nie katalog główny projektu. - Build się wykonał. Przeczytaj log wdrożenia. Jeśli build się nie powiódł, host mógł nie wdrożyć niczego albo wdrożyć starą wersję.
index.htmlleży na najwyższym poziomie opublikowanego folderu, a nie w podfolderze.- Ścieżka bazowa się zgadza. Jeśli aplikacja działa pod
example.com/app/, musi być zbudowana z tą bazą (opcjabasew Vite,basenamew React Router), inaczej każda trasa i zasób będzie chybiony.
Krok 4: Napraw brakujące pliki i błędne ścieżki
Gdy strony się ładują, ale zasoby dają 404:
- Wielkość liter. macOS i Windows zwykle traktują
Logo.pngilogo.pngjako ten sam plik. Większość serwerów Linux już nie. Każde odwołanie musi dokładnie odpowiadać nazwie pliku. - Pliki poza buildem. W Vite pliki w
public/są kopiowane bez zmian i odwołuje się do nich z korzenia (/logo.png). Pliki importowane w kodzie są wbudowywane w bundle. Plik leżący gdzieś indziej w projekcie może w ogóle nie zostać wdrożony. - Ścieżki względne.
images/photo.jpgjest rozwiązywane względem bieżącego adresu, więc przestaje działać na/blog/post-1. Użyj/images/photo.jpg. - Przesłane pliki zapisywane na dysku lokalnym. Jeśli przesyłane przez użytkowników pliki trafiały do folderu na serwerze, znikają przy wdrożeniu nowej wersji. Użyj odpowiedniego magazynu plików.
Krok 5: Obsługuj końcowe ukośniki konsekwentnie
/about i /about/ to różne adresy. Hosty różnią się tym, czy dodają lub usuwają ukośnik, a niezgodność z linkami lub routerem może dać 404 albo pętle przekierowań. Wybierz jeden styl, ustaw linki w tym stylu i skonfiguruj host, żeby przekierowywał drugą formę na niego. Spójność pomaga też wyszukiwarkom, które inaczej mogą widzieć dwie kopie każdej strony.
Krok 6: Napraw trasy API, które dają 404
Jeśli strona się ładuje, ale w zakładce Sieć żądania /api/... zwracają 404:
- Backend nie jest wdrożony. Hosting statyczny serwuje tylko pliki; backend musi działać gdzieś indziej.
- Ścieżka jest routowana inaczej na produkcji. W developmencie proxy mogło przekazywać
/apido osobnego serwera. Na produkcji host potrzebuje odpowiedniego rewrite'u, albo front-end musi wywoływać prawdziwy adres API. - Fallback SPA przechwycił żądanie. Żądanie API, które zwraca
index.htmlze statusem 200, oznacza, że reguła fallbacku jest zbyt szeroka. Wyklucz z niej/api/*.
Opublikowana aplikacja zwraca 404 dla żądań do /api/orders, ale w podglądzie działają. Sprawdź, jak /api jest routowane w podglądzie i w opublikowanej aplikacji, i spraw, by opublikowany front-end docierał do backendu w ten sam sposób.
Krok 7: Przekieruj stare adresy
Jeśli przeniosłeś się z innej strony lub zmieniłeś strukturę, stare adresy, których nadal używają ludzie i wyszukiwarki, będą dawać 404. Dodaj przekierowanie 301 (stałe) z każdego starego adresu na nowy. Prowadź listę i po starcie sprawdź próbkę. Nasz przewodnik migracji strony WordPress pokazuje, jak zbudować taką listę.
Krok 8: Sprawdź domenę
Jeśli aplikacja działa pod adresem hosta, ale na Twojej domenie zwraca 404, domena może wskazywać na zły projekt albo host nie ma jeszcze podpiętej tej domeny do Twojej strony. Sprawdź rekordy DNS i ustawienia domeny w hoście. Zobacz jak podłączyć własną domenę.
Spraw, by prawdziwa strona 404 była użyteczna
Niektóre 404 są poprawne: ktoś źle wpisał adres. Zrób tę stronę pomocną:
- Krótka wiadomość i link do strony głównej oraz kluczowych sekcji
- Pole wyszukiwania, jeśli strona ma wyszukiwarkę
- Ten sam nagłówek i nawigacja co w reszcie strony
Tam, gdzie konfiguracja na to pozwala, zwracaj prawdziwy status 404 dla stron, które nie istnieją. Komunikat "nie znaleziono" zwrócony ze statusem 200 to tzw. miękki błąd 404; może marnować czas indeksowania przez wyszukiwarki i mylić indeksowanie.
Częste błędy
- Testowanie tylko przez klikanie. Zawsze testuj, wklejając głębokie adresy do nowej karty i odświeżając.
- Fallback, który łapie wszystko. Zasoby i trasy API zwracają
index.html, co daje puste strony i mylące błędy API. - Niezgodna wielkość liter, która psuje się tylko na serwerze.
- Wdrażanie folderu źródłowego zamiast wyniku builda.
- Zmiana struktury adresów bez przekierowań. Każdy stary link staje się 404.
404 w Mythex
W Mythex publikujesz z przestrzeni roboczej, a statyczne front-endy wdrażane są jako strony statyczne. Jeśli opublikowana strona daje 404, podaj agentowi dokładny adres, napisz, czy błąd pojawia się po odświeżeniu, czy po kliknięciu, i co pokazuje zakładka Sieć, i poproś o sprawdzenie routingu. Po poprawce opublikuj ponownie, bo działająca aplikacja to migawka do czasu ponownej publikacji. Jeśli ostatnio zmieniłeś projekt, a strona na żywo wygląda na starą, opublikuj ponownie i odśwież z wymuszeniem. Jeśli build się nie powiedzie, użyj Napraw z AI w oknie publikacji. Zobacz Jak publikować i Rozwiązywanie problemów z publikacją w dokumentacji oraz nasz przewodnik jak debugować aplikację zbudowaną z AI.
Lista kontrolna 404
- Zanotowano dokładnie, które adresy dają 404 i czy po kliknięciu, odświeżeniu, czy po obu
- Fallback SPA zwraca
index.htmldla tras aplikacji, ze statusem 200 - Fallback wyklucza prawdziwe pliki i
/api/* - Router ma trasę "nie znaleziono" przechwytującą wszystko
- Opublikowany jest folder wyniku builda i build się powiódł
- Ścieżka bazowa zgadza się z miejscem, w którym działa aplikacja
- Wielkość liter w nazwach plików zgadza się z każdym odwołaniem
- Ścieżki zasobów zaczynają się od
/ - Styl końcowych ukośników jest spójny
- Trasy API są wdrożone i routowane na produkcji
- Przekierowania 301 dla starych adresów
- Głębokie linki przetestowane przez wklejenie do nowej karty
Pytania
Dlaczego w mojej aplikacji React po odświeżeniu strony pojawia się 404?
W aplikacji jednostronicowej trasy takie jak /dashboard istnieją tylko w JavaScripcie. Kliknięcie linku działa, bo router obsługuje to w przeglądarce, ale odświeżenie prosi serwer o plik /dashboard, którego nie ma. Rozwiązaniem jest reguła, która zwraca index.html dla tras aplikacji.
Jak dodać fallback SPA w Netlify, Vercel lub Nginx?
W Netlify dodaj plik _redirects z regułą /* /index.html 200. W Vercel dodaj rewrite w vercel.json, który kieruje wszystkie ścieżki do /index.html. W Nginx użyj try_files $uri $uri/ /index.html; w bloku location. Sprawdź dokumentację swojego hosta, bo zasady się zmieniają.
Dlaczego po wdrożeniu moje obrazy lub pliki dają 404?
Zwykle plik nie trafił do wyniku builda, wielkość liter w ścieżce nie zgadza się (serwery często rozróżniają wielkość liter, a Twój laptop nie), albo ścieżka jest względna, a powinna zaczynać się od ukośnika.
Czy brakująca strona powinna zwracać prawdziwy status 404?
Tak. Pokaż pomocną stronę "nie znaleziono", ale ze statusem 404, o ile Twoja konfiguracja na to pozwala. Wyszukiwarki traktują komunikat "nie znaleziono" zwrócony ze statusem 200 jako miękki błąd 404, co marnuje czas indeksowania i może mylić indeksowanie.