Kategoria: Next.js, React i TypeScript

Next.js: useSearchParams psuje statyczną stronę błędu 404

Poradnik techniczny · Kacper Bernecki

Podczas next build występuje komunikat o brakującej granicy Suspense na /_not-found, chociaż strona główna działa. Hook odczytujący query string może być renderowany przez wspólny layout, nawet gdy nie ma go w samym pliku strony błędu.

Jak ustalić źródło błędu

Przejrzyj layout.tsx i wszystkie współdzielone elementy nagłówka lub menu korzystające z useSearchParams.

Uruchom produkcyjny build i odczytaj pełny trace, aby znaleźć komponent powodujący wyłączenie statycznego renderowania.

Co zrobić krok po kroku

1. Wydziel komponent kliencki z hookiem i otocz go Suspense jak najbliżej miejsca użycia, pozostawiając resztę strony renderowaną na serwerze.

2. Jeżeli strona naprawdę ma być dynamiczna, wybierz świadomie dynamic rendering zamiast sztucznie wyłączać reguły buildu.

Jak sprawdzić wynik

Build kończy się bez błędu /_not-found, a obsługa 404 i wyszukiwanie w menu działają po przeładowaniu.

Czego nie robić

Nie usuwaj całego mechanizmu routingu ani nie ukrywaj problemu przez wyłączenie lintowania.