Przejdź do treści

Jak debugować Next.js? Cache i Hydration Errors

Maciej Sala

Founder StriveLab

6 min czytaniaAktualizacja

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
Code
// DOBRZE — osobny plik komponentu
'use client'
 
import { useEffect, useState } from 'react'
 
function TimeStamp() {
  const [time, setTime] = useState<string>('')
  useEffect(() => setTime(new Date().toLocaleString()), [])
  return <p>{time}</p>
}
Code
// 2. window/document — nie istnieją na serwerze
// ŹLE
;<p>Szerokość: {window.innerWidth}px</p> // window is not defined on server
Code
// DOBRZE — osobny plik komponentu
'use client'
 
import { useEffect, useState } from 'react'
 
function ScreenWidth() {
  const [width, setWidth] = useState(0)
  useEffect(() => setWidth(window.innerWidth), [])
  return <p>Szerokość: {width}px</p>
}
Code
// 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 cache
const 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ź revalidate
export 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.js
rm -rf .next
 
# Restart dev servera
npm 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 trasy
export 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 żądanie
export 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 serwerze
export 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>
}

VS Code debugger dla React Server Components

Code
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev -- --inspect"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    }
  ]
}
Code
# Uruchom Next.js z debuggerem
npm 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:

Code
// proxy.ts — Next.js 16
import { NextResponse, type NextRequest } from 'next/server'
 
export function proxy(request: NextRequest) {
  const start = Date.now()
 
  // ... logika proxy
  const response = NextResponse.next()
 
  const duration = Date.now() - start
  console.log(
    JSON.stringify({
      type: 'proxy',
      path: request.nextUrl.pathname,
      method: request.method,
      duration: `${duration}ms`,
      userAgent: request.headers.get('user-agent')?.slice(0, 50),
    }),
  )
 
  return response
}

Narzędzia do debugowania Next.js

React DevTools: Components i Profiler

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.ts
const 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:

Code
// Globalny fetch logger (development only)
if (process.env.NODE_ENV === 'development') {
  const originalFetch = global.fetch
  global.fetch = async (...args) => {
    const input = args[0]
    const url =
      typeof input === 'string'
        ? input
        : input instanceof URL
          ? input.href
          : input.url
    console.log(`[FETCH] ${url}`)
    const start = Date.now()
    const result = await originalFetch(...args)
    console.log(`[FETCH] ${url} → ${result.status} (${Date.now() - start}ms)`)
    return result
  }
}
Audyt techniczny i optymalizacja SEO.
Audyt techniczny SEO

Często zadawane pytania

Jak debugować Next.js na produkcji?

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.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat Next.js i React

Czytaj dalej

Zobacz więcej wpisów
Hydration mismatch a SEO i indeksowanie w Next.js

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

Maciej Sala

Founder StriveLab

Server i Client Components w Next.js: gdzie przebiega granica serwer–klient

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

Maciej Sala

Founder StriveLab

Astro czy Next.js w 2026: porównanie frameworków

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 .

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G