Next.js
Debugging en Next.js
Explica cómo localizar fallos según fase y runtime: build, prerender, request, RSC, streaming, hidratación, navegación, caché y deployment.
- Última actualización
- Actualizada
- Nivel
- Aplicación
Next.js
Explica cómo localizar fallos según fase y runtime: build, prerender, request, RSC, streaming, hidratación, navegación, caché y deployment.
Depurar Next.js empieza identificando la fase y el runtime. Un fallo puede ocurrir durante análisis del módulo, build, prerender, request servidor, generación RSC, streaming, hidratación o navegación cliente. Mirar únicamente la consola del navegador deja fuera gran parte del sistema.
source import
→ next dev analysis
→ next build
→ prerender/cache fill
→ request server execution
→ HTML/RSC stream
→ hydration
→ client navigation/interactionsPregunta primero: ¿dónde ocurre, con qué entrada y bajo qué release?
next build && next start.Un bug “solo Vercel” puede ser runtime, env, región, case sensitivity o caché; no necesariamente la plataforma.
Dev incluye Fast Refresh, source maps, recompilación y comportamiento menos optimizado. Production añade:
Reproduce con build antes de atribuirlo a hosting.
terminal/platform logs
→ Server Components, Actions, Handlers, build
browser console
→ Client Components, hydration, chunks, runtime JSUn console.log dentro de Server Component no aparece necesariamente en DevTools. Añade request ID para correlacionar.
Causas:
Date.now()/Math.random() durante render.window/storage para elegir rama inicial.Proceso:
useId para IDs.No tapes todo con suppressHydrationWarning.
Errores típicos:
import server-only module into Client Component
non-serializable prop crosses RSC boundary
hook used in Server Component
browser API used on serverSigue el grafo desde el archivo "use client": todos sus imports pasan al bundle cliente. Mueve acceso DB/secrets a DAL y pasa DTO serializable.
Lee la primera causa real, no solo el final del worker. Revisa:
Ejecuta con misma versión Node y package manager del CI.
Pregunta qué capa:
browser/router cache?
CDN?
full route output?
use cache entry?
fetch/data cache?
provider cache?
DB replica?Comprueba key, lifetime, tag e invalidación. Añade un campo de versión/updatedAt para saber qué snapshot ves. No “arregles” todo con no-store sin localizar la capa.
Conflictos:
notFound() capturado.Inspecciona árbol app, URL exacta y output de build.
DevTools Network muestra:
/_next/image.Revisa status, redirect chain, content type, cache headers y payload. Un 200 con HTML para un chunk indica rewrite/proxy/CDN mal configurado.
Diagnóstico:
¿form submit llegó?
¿session válida?
¿schema pasó?
¿service committed?
¿invalidación ocurrió?
¿UI recibió state/redirect?No loggees FormData completa. Prueba invocación directa y doble submit.
Usa breakpoints en VS Code/Chrome para Node y browser. Los source maps deben corresponder al release. Para producción, sube mapas privados al error tracker y conserva commit.
Performance panel + server traces:
No confundas un render React lento con TTFB servidor.
remove half of tree
→ bug remains?
├─ yes → keep reduced half
└─ no → restore relevant halfSustituye dependencia por valor fijo, desactiva cache localmente y elimina providers hasta aislar. Cambia una variable cada vez.
Oculta race/cache.
Ignora servidor/build.
Puede limpiar síntoma, no causa.
No sabes qué corrigió.
Muchos anticipan fallos de producción.
La reproducción deja de ser equivalente.
Árbol, params, matcher, rewrite, notFound, case.
Capa de caché, tag, commit e invalidación.
Build, env, runtime, cache, minificación, región.
Deploy atómico, CDN y pestaña vieja.
Determinismo, HTML, locale, browser API.
Logs servidor, digest, dependencia, timeout.
use client para fugas.next start?.next no es una corrección?TypeScript en Next.js reduce estados imposibles, pero no reemplaza validación runtime.