Kategoria: Next.js, React i TypeScript

Next.js: notFound() działa w trybie devel, ale po buildzie strona zwraca 404

Poradnik techniczny · Kacper Bernecki

Opisany objaw — notFound() poprawnie renderuje stronę 404 podczas pracy w next dev, lecz po wykonaniu next build i wdrożeniu użytkownik otrzymuje 404 albo inny routing — wskazuje na różnice konfiguracji między środowiskiem deweloperskim a produkcją. Najczęstsze przyczyny to: błędne użycie getStaticProps/getServerSideProps zamiast logiki App Router, nieodpowiednie miejsce wywołania notFound (np. w komponencie klienta), nieprawidłowe ustawienia catch-all lub segmentów dynamicznych w plikach app/, a także problem z eksportem statycznym (next export) lub rewrites w konfiguracji hosta. Poniższa analiza rozróżnia wersje routingu, sprawdza generowanie stron przy buildzie i dostarcza sekwencyjne testy reprodukcji oraz poprawki, które można wykonać lokalnie i na serwerze CI/CD.

Jak rozpoznać przyczynę

Sprawdź, czy używasz App Router (folder app/) czy Pages Router (folder pages/). notFound() jest API App Router i wywołanie go w komponentach lub funkcjach związanych z Pages Router nie zawsze będzie skutkować tym samym zachowaniem po buildzie. Upewnij się, że plik, w którym dzwonisz notFound(), to serwerowy komponent (.tsx/.jsx) lub serwerowa funkcja (np. w layoutach lub page.tsx z async).

Zbadaj typ renderowania: jeśli dany segment jest generowany statycznie (static), a w dev masz fallback dynamiczny, może dojść do sytuacji, że build zadecydował o wygenerowaniu trasy inaczej. Upewnij się, czy eksportujesz stronę statycznie (next export) — notFound() w App Router nie działa przy pełnym static export bez obsługi 404 przez serwer.

Sprawdź rewrites, redirects i konfigurację hosta (Vercel, Netlify, nginx). W dev lokalny serwer Next.js obsługuje notFound() bezpośrednio, ale serwer produkcyjny może nadpisywać ścieżki lub zwracać 404 przed dotarciem do aplikacji (np. reguły serwera blokują ścieżkę) — w takim wypadku aplikacja nie ma szansy wywołać notFound().

Rozwiązanie krok po kroku

1. Weryfikacja routera: Otwórz strukturę projektu i potwierdź, że problematyczna trasa znajduje się w katalogu app/. Jeśli jest w pages/, nie używaj notFound(); zamiast tego zwróć obiekt z getStaticProps/getServerSideProps lub use next/router do redirectów. Zmiana miejsca pliku może wymagać refaktoringu komponentu.

2. Upewnij się, że notFound() wywoływane jest w kodzie serwerowym: przenieś logikę decydującą o 404 do async server component lub do funkcji fetch w page.tsx (np. w miejscu, gdzie pobierasz dane). Dodaj console.log() lub debug informacji do build-time/logs serwera, aby potwierdzić, że kod jest uruchamiany podczas requestów produkcyjnych.

3. Sprawdź wynik builda: uruchom next build lokalnie i przeanalizuj output. Jeżeli używasz generowania statycznego, sprawdź, czy trasa jest pre-renderowana. Następnie uruchom next start lokalnie na buildzie i odtwórz scenariusz, aby sprawdzić czy 404 występuje już na lokalnym buildzie.

4. Skontroluj konfigurację next.config.js: poszukaj settings związanych z output: 'export' lub trailingSlash, oraz rewrites/redirects; tymczasowo skomentuj rewrites/redirects, uruchom build i testuj zachowanie notFound(). Jeśli błąd znika, zidentyfikuj regułę, która koliduje.

5. Przegląd serwera hosta: jeśli hostujesz na Vercel/Netlify/NGINX, sprawdź ich logi i reguły routingu. Na Vercel upewnij się, że deployment używa właściwej wersji Next.js obsługującej App Router i że nie wykorzystujesz 'static site generation' bez dynamicznej obsługi 404.

6. Test z minimalistycznym przykładem: stwórz prosty app/page.tsx z fragmentem async który zawsze wywołuje notFound() i zrób full build+start. To izoluje problem od reszty aplikacji i pokaże, czy podstawowe notFound działa w twoim środowisku produkcyjnym.

7. Jeśli używasz middleware lub catch-all route, tymczasowo wyłącz middleware i przetestuj. Middleware może przechwytywać requesty wcześniej i zwracać odpowiedź 404 lub redirect przed osiągnięciem strony, co tłumaczy różnicę między dev a buildem.

Jak sprawdzić, czy problem zniknął

Test lokalny na buildzie: uruchom next build && next start i wykonaj żądanie do problematycznej ścieżki. Oczekuj, że minimalny testowy page.tsx wywołujący notFound() zwróci aplikacyjny 404. Jeśli lokalny build działa, problem leży w hostingu/rewrites.

Test z wyłączonymi rewrites/middleware: na środowisku staging wdrożenie z tymczasowo skomentowanymi regułami rewrites i middleware. Jeśli notFound działa po ich wyłączeniu, przywracaj reguły pojedynczo aby zlokalizować konflikt.

Test izolowany: wdroż prosty repo z jednym page.tsx w app/ który zawsze wywołuje notFound(); zdeploj na to samo środowisko produkcyjne. Jeżeli prosty przypadek zwraca 404 prawidłowo, problem tkwi w specyficznej logice twojej aplikacji (routing dynamiczny, getStaticPaths, etc.).

Czego nie robić

Nie zakładaj, że dev mirroruje produkcję: najczęstszy błąd to ignorowanie różnic build-time i serwera hostującego — testuj na buildzie lokalnie oraz w stagingu przed produkcyjnym deployem.

Unikanie izolacji problemu: nie wprowadzaj zmian globalnych bez testu w minimalnym projekcie; to utrudnia identyfikację czy błąd leży w Next.js, konfiguracji hosta, czy własnym middleware.

Mieszanie App i Pages Router: wywoływanie notFound() w kontekście Pages Router lub w komponencie klienta spowoduje nieprzewidywalne zachowanie po buildzie — upewnij się, że logika 404 jest serwerowa i w folderze app/.