Kategoria: Next.js, React i TypeScript

Next.js: odczyt headers() blokuje statyczne prerenderowanie

Poradnik techniczny · Kacper Bernecki

Strona wcześniej była generowana statycznie, a po dodaniu headers() przechodzi na tryb dynamiczny lub build zgłasza ostrzeżenie. Odczyt nagłówków zależy od konkretnego żądania i może uniemożliwiać wykonanie całej trasy jako stałego HTML przy buildzie.

Jak rozpoznać źródło problemu

Sprawdź, gdzie wywołujesz headers() i czy komponent jest używany przez wszystkie podstrony w layout. Zweryfikuj, czy wymagane informacje rzeczywiście zależą od requestu, czy są stałą konfiguracją aplikacji.

Porównaj komunikat z konsoli z wynikiem kompilacji produkcyjnej oraz stanem po odświeżeniu strony.

Kroki naprawcze

Przenieś logikę zależną od nagłówków do wyraźnej dynamicznej trasy lub mniejszego wydzielonego fragmentu. Dla treści publicznych użyj stałej konfiguracji, gdy nagłówek nie jest wymagany do renderowania.

Jak przetestować rozwiązanie

Trasy mają zamierzony tryb renderowania, a build nie zmienia go przypadkowo przez wspólny layout.

Bezpieczeństwo i ograniczenia

Nie próbuj odczytywać prywatnych nagłówków użytkownika w statycznie wygenerowanym HTML.