Szybka odpowiedź: jak debugować cache i błędy hydratacji w Next.js?
Najpierw ustal warstwę, bo miejsce wyświetlenia logu nie zawsze wskazuje miejsce wykonania kodu.
Błąd hydratacji może wynikać z różnego czasu, losowych wartości lub struktury HTML w pierwszym renderze.
Przy starych danych sprawdź cache i ustal, czy aplikacja używa Cache Components, czy poprzedniego modelu.
Cache testuj na buildzie produkcyjnym po next build i next start.
Wynik Server Actions zawsze obsługuj i pokazuj, bo potrafią zawieść bez śladu w interfejsie.
Dlaczego debugowanie Next.js jest trudniejsze niż klasycznego Reacta?
Zanim wejdziemy w konkretne problemy, jedna mapa, która oszczędza najwięcej czasu — od objawu do właściwej warstwy i narzędzia:
Diagram
Ścieżka diagnozy: najpierw ustal warstwę, w której występuje objaw, dopiero potem sięgaj po narzędzie.
Problem 1: hydration mismatch w Next.js
Typowy komunikat w Next.js: „Hydration failed because the initial UI does not match what was rendered on the server." pojawia się, gdy serwer i klient renderują inny początkowy wynik.
Typowe przyczyny hydration mismatch
Code
// 1. Date/Time — serwer i klient mają różne timezone/czas// ŹLE;<p>Wygenerowano: {new Date().toLocaleString()}</p>// Serwer: "11.04.2026, 10:00:00" → Klient: "11.04.2026, 10:00:01" → MISMATCH
// 3. Math.random() — różny wynik na serwerze i kliencie// ŹLE// <div style={{ order: Math.random() }}>...</div>// DOBRZE — użyj deterministycznego źródła<div style={{ order: hashString(item.id) }}>...</div>
Rozszerzenia przeglądarki: najpierw sprawdź stronę w profilu bez rozszerzeń. suppressHydrationWarning działa tylko jeden poziom w głąb i nie naprawia zmian struktury DOM; stosuj je punktowo wyłącznie dla świadomie zaakceptowanej różnicy. Odczyt window na serwerze to z kolei błąd wykonania — przeniesienie go do efektu zapobiega temu błędowi.
Jak debugować hydration errors w Next.js?
Współczesny Next.js pokazuje diff w dev overlay — porównanie HTML serwera vs klienta. Jeśli diff jest nieczytelny:
Code
// Osobny Client Component'use client'import dynamic from 'next/dynamic'const SuspectedComponent = dynamic(() => import('./suspected'), { ssr: false, // Test diagnostyczny: pomiń prerenderowanie tego komponentu})
ssr: false nie jest dozwolone bezpośrednio w Server Component. Zniknięcie błędu zawęża diagnozę do prerenderowania/hydratacji, ale nie wskazuje jeszcze przyczyny.
Problem 2: cache w Next.js i dane, które się nie odświeżają
„Zmieniłem dane w bazie, ale strona pokazuje stare."
Diagnostyka cache w App Routerze
Poniższe opcje konfiguracyjne (dynamic oraz revalidate) odnoszą się wyłącznie do aplikacji **bez aktywnej flagi cacheComponents: true**. W trybie Cache Components korzystaj z dyrektywy use cacheoraz funkcjicacheLifeicacheTag – wspomniane eksporty nie są tam obsługiwane.
Code
// 1. Sprawdź, czy strona jest statyczna czy dynamiczna// Build output pokaże:// ○ = Static (cachowana w build)// ƒ = Dynamic (renderowana per request)// ● = SSG (sam symbol nie oznacza ISR)// ◐ = częściowy prerendering ze strumieniowanymi fragmentami dynamicznymi// 2. Sprawdź fetch cacheconst data = await fetch(url, { cache: 'no-store', // Pomija Data Cache tego fetcha; w dev uwaga na HMR // cache: 'force-cache', // Jawnie włącza cache — od Next.js 15 fetch domyślnie NIE jest cachowany})// 3. Sprawdź revalidateexport const revalidate = 0 // Wymusza dynamiczne renderowanie// export const revalidate = 3600; // Po godzinie kolejny request uruchamia rewalidację
Zachowanie statycznego renderowania i ISR sprawdzaj po next build && next start. Dev renderuje strony na żądanie, lecz cache odpowiedzi fetch pomiędzy odświeżeniami HMR może zachować stare dane nawet przy no-store. Spróbuj pełnego przeładowania; diagnostycznie możesz wyłączyć experimental.serverComponentsHmrCache. Symbol dynamicznej trasy nie dowodzi, że wszystkie jej dane są pobierane bez cache.
Czyszczenie cache Next.js w development
Code
# Najpierw zatrzymaj dev server, potem usuń lokalne artefakty Next.jsrm -rf .next# Restart dev serveranpm run dev
Debugowanie revalidation w Next.js
Code
// Server Action — dodaj logi do revalidation'use server'import { revalidatePath, revalidateTag } from 'next/cache'export async function updatePost(id: string, data: PostData) { await db.post.update({ where: { id }, data }) console.log(`[REVALIDATE] Path: /blog/${id}`) revalidatePath(`/blog/${id}`) console.log(`[REVALIDATE] Tag: post-${id}`) revalidateTag(`post-${id}`, 'max')}
Tag post-${id} musi być wcześniej przypisany do danych przez next.tags, cacheTag lub opcje unstable_cache. Profil 'max' pozwala zwracać starą wartość podczas odświeżania; w Server Action użyj updateTag, jeśli kolejny odczyt ma czekać na świeży wynik.
Eksporty dynamic i revalidate
Warianty alternatywne dla page.tsx lub layout.tsx bez Cache Components:
Code
// Renderowanie per request; pomija cache fetchy tej trasyexport const dynamic = 'force-dynamic'// Alternatywnie: prerenderowanie; cookies/headers zwracają puste wartości// export const dynamic = 'force-static'// Alternatywnie: zgłoś błąd przy dynamicznych API lub niecache'owanych danych// export const dynamic = 'error'
Code
// Próg rewalidacji: po godzinie odświeżanie uruchamia kolejne żądanieexport const revalidate = 3600// Alternatywnie: render per request; jawnie cache'owane fetche pozostają cache'owane// export const revalidate = 0
Problem 3: debugowanie Server Components i console.log
To pytanie zadaje sobie każdy, kto pierwszy raz dotyka App Routera. wykonuje się na serwerze, więc logów szukaj przede wszystkim w terminalu lub logach hostingu. W dev React może odtwarzać je również w konsoli przeglądarki.
Code
// Server Component — kod wykonuje się na serwerzeexport default async function ProductPage() { const product = await getProduct('123') console.log('Product data:', product) // ← Terminal (serwer) return <div>{product.name}</div>}
Code
// Client Component — render może wykonać się także podczas SSR'use client'export function AddToCartButton() { console.log('Button rendered') // ← SSR: serwer; hydratacja: przeglądarka return <button onClick={() => console.log('Clicked!')}>Dodaj</button>}
# Uruchom Next.js z debuggeremnpm run dev -- --inspect
W VS Code uruchom konfigurację server-side; komenda powyżej jest alternatywą przy ręcznym podłączaniu do adresu debuggera wypisanego w terminalu. Do debugowania obu stron po uruchomieniu serwera włącz też konfigurację client-side.
Teraz możesz ustawiać breakpointy w Server Components, Server Actions i Route Handlers — VS Code zatrzyma się na nich.
Problem 4: Server Actions i ciche błędy
Sam formularz z action={...} jest poprawny. Jeśli jednak akcja zwraca stan spodziewanego błędu, trzeba go odczytać i wyświetlić — jednym ze sposobów jest useActionState:
Code
'use client'import { useActionState } from 'react'import { deletePost } from '@/app/actions/posts' // Server Action zwracająca { success, error? }function DeleteButton({ postId }: { postId: string }) { const [state, formAction, isPending] = useActionState( // Akcja dostaje (poprzedni stan, formData); to co ZWRÓCI, ląduje w state async () => deletePost(postId), // zwraca { success, error? } null, ) return ( <form action={formAction}> <button disabled={isPending}>{isPending ? 'Usuwanie...' : 'Usuń'}</button> {state && !state.success && <p className="text-red-500">{state.error}</p>} </form> )}
Zwróć uwagę, że Server Action zwraca obiekt błędu, zamiast rzucać wyjątek. To nie jest kwestia stylu, lecz architektury: rzucony błąd omija stan formularza (state) i wędruje wyżej do najbliższego error boundary, a w środowisku produkcyjnym Next.js dodatkowo maskuje jego treść. Komunikat, który chcesz wyświetlić użytkownikowi przy formularzu, musi być zwracaną wartością – dlatego przy spodziewanych błędach walidacji czy logiki zwracaj strukturę typu { success, error }, a throw zarezerwuj wyłącznie dla nieoczekiwanych awarii.
Problem 5: debugowanie middleware i proxy w Next.js
Warstwa pośrednicząca między żądaniem a trasą bywa trudna do podejrzenia, bo działa poza zwykłym cyklem komponentów. W Next.js 16 plik middleware.ts został przemianowany na proxy.ts (a funkcja na proxy) i działa na runtime Node; w starszych wersjach używano middleware.ts, domyślnie na Edge Runtime; późniejsze wersje 15 wspierały także Node.js. Niezależnie od wersji pomaga structured logging:
React DevTools w Chrome/Firefox pokazuje drzewo komponentów, propsy, state i konteksty. Profiler mierzy czas renderowania — szukaj komponentów, które renderują się zbyt często.
React DevTools od wersji 6 obsługuje również Server Components w drzewie. Ich widoczność zależy od integracji frameworka i filtrów; nie oznacza to, że kod komponentu serwerowego wykonuje się w przeglądarce.
Next.js Dev Overlay
Automatycznie wyświetla się w dev mode przy błędach: hydration mismatch, runtime errors, build errors. Kliknij na błąd — przeniesie Cię do linii kodu w edytorze.
Network tab: sprawdź, co fetchuje Next.js
Chrome DevTools → Network → filtruj po Fetch/XHR. Widzisz requesty z Client Components. Server Components fetchują na serwerze — ich requesty nie pojawiają się w Network tab przeglądarki.
Żeby zobaczyć server-side fetch, zacznij od wbudowanej opcji — Next.js potrafi logować fetche z Server Components w terminalu dev servera, razem ze statusem cache (HIT/MISS/SKIP):
Code
// next.config.tsconst nextConfig = { logging: { fetches: { fullUrl: true, // pełne URL-e zamiast skróconych hmrRefreshes: true, // także odpowiedzi odtworzone z cache HMR }, },}export default nextConfig
Dopiero gdy potrzebujesz czegoś więcej (czasy, własny format, fetch spoza Next.js), sięgnij po ręczny interceptor:
Na produkcji console.log nie wystarcza, ponieważ potrzebujesz prawdziwego monitoringu. Sentry zbierze błędy i opcjonalnie nagrania sesji, Vercel Speed Insights albo własny reporter Core Web Vitals pokaże wydajność u realnych użytkowników, a structured logging (JSON do stdout zbierany przez agregator) pozwoli przeszukiwać zdarzenia. Klucz to logować w formacie nadającym się do filtrowania i alarmowania, a nie tylko wypisywać tekst.
Czy mogę użyć debuggera w Server Components?
Tak. Użyj konfiguracji VS Code typu node-terminal z komendą npm run dev -- --inspect, aby debugować proces serwera. Breakpoint ustawiony w Server Component, Server Action albo Route Handlerze zatrzyma serwer dokładnie na tej linii, dając pełny wgląd w zmienne i stos wywołań i to tak samo jak przy debugowaniu zwykłego kodu backendowego.
Jak sprawdzić, czy komponent jest Server czy Client?
Dyrektywa 'use client' wyznacza granicę klienta: obejmuje moduł i jego importowane zależności. Brak dyrektywy w danym pliku nie przesądza więc, że komponent jest serwerowy — sprawdź drzewo importów. Współczesne React DevTools potrafią pokazywać również Server Components.
Dlaczego mój console.log nie pojawia się w przeglądarce?
Jeśli log pochodzi z Server Component, szukaj go przede wszystkim w terminalu lub logach hostingu. W dev może być również odtwarzany w przeglądarce. Client Components są prerenderowane na serwerze, więc log w ich renderze może pojawić się po obu stronach; log w obsłudze kliknięcia wykonuje się w przeglądarce.
Dlaczego cache zachowuje się inaczej w dev niż na produkcji?
W trybie dev odpowiedzi fetch (nawet z cache: 'no-store') mogą przetrwać odświeżenie HMR – jeśli podejrzewasz taki efekt, przeładuj całą stronę. Statyczny render i ISR testuj zawsze na gotowej wersji produkcyjnej (next build && next start). Miej też na uwadze, że oznaczenia z buildu informują o sposobie renderowania stron, a nie o cache'owaniu samych danych.
Co najczęściej powoduje hydration mismatch?
Typowe przyczyny to różny czas, losowe wartości, nieprawidłowe zagnieżdżenie HTML i rozszerzenia modyfikujące DOM. Pierwszy render serwera i klienta powinien być zgodny; dane dostępne tylko w przeglądarce można odczytać w useEffect. Bezpośredni odczyt window na serwerze powoduje błąd wykonania, nie sam mismatch. Rozszerzenia sprawdź w czystym profilu; suppressHydrationWarning wycisza tylko lokalną, świadomie zaakceptowaną różnicę i nie naprawia struktury DOM.
O autorze
Maciej Sala
Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.
Hydratacja jest momentem, w którym HTML z serwera spotyka się z renderem z JavaScriptu. W sytuacji, kiedy te dwie wersje pokazują inną treść, problem wychodzi poza konsolę i Googlebot może dostać inną stronę niż użytkownik. Nie powinieneś ignorować komunikatu Hydration failed . Sam błąd nie jest czynnikiem rankingowym, ale jego skutki mogą utrudnić renderowanie i indeksowanie ważnej treści.
Maciej Sala
Founder StriveLab
Komponent działa lokalnie, ale po wdrożeniu na produkcję pojawia się niezgodność hydratacji ang. hydration mismatch , a prosta strona produktu pobiera kilkaset kilobajtów JavaScriptu. Zamiast natychmiast wyłączać SSR czy otaczać kod memoizacją, warto cofnąć się o krok. Problem rzadko leży w braku optymalizacji — częściej w braku decyzji, która część interfejsu realnie wymaga przeglądarki. React Server Components przesunęły granicę między serwerem a klientem. W App Routerze najpierw decydujemy, gdzie wykonać pracę, a dopiero potem dobieramy hooki i biblioteki.
Maciej Sala
Founder StriveLab
Astro czy Next.js? Wybór frameworka musi być dokładnie przemyślany, zanim pojawi się pierwszy commit. Jeśli stoisz przed takim właśnie wyborem, w tym artykule staram się wykazać, w jakich obszarach najlepiej sprawdza się Astro , a w jakich będzie dominował Next.js .