Next.js Debugging

Next.js 오류 진단 흐름

개발 환경 오류는 설치, 포트, TypeScript, 서버 렌더링, fetch, DB, hydration 단계별로 나누면 원인 위치가 빨리 좁혀진다.

01

실행 전 오류

패키지 설치, Node 버전, lockfile, 포트 충돌을 먼저 확인한다.

setup
02

컴파일 오류

TypeScript와 ESLint 메시지에서 파일, 타입, import 경로를 분리해 읽는다.

compile
03

서버 오류

Server Component와 Route Handler에서 fetch, env, DB 연결 실패를 로그로 좁힌다.

서버 경로
04

Hydration 오류

서버 HTML과 클라이언트 첫 렌더가 달라지는 날짜, 랜덤, 브라우저 API 사용을 찾는다.

client mismatch
EADDRINUSE
개발 서버 포트가 이미 사용 중이면 프로세스 종료나 포트 변경이 필요하다. 서버가 두 개 떠 있으면 HMR과 API 테스트가 엉킬 수 있다.
port conflict
fetch
서버 fetch는 절대 URL, 캐시 정책, 인증 헤더를 함께 확인한다. 클라이언트 fetch와 서버 fetch의 쿠키 전달 방식이 다르다.
SSR 경계
Hydration
렌더 시점마다 달라지는 값은 클라이언트 effect 이후로 이동한다. Date.now, Math.random, window 접근이 흔한 원인이다.
deterministic first render

오류 원인 분류 기준

재현 단계 오류가 install, dev, build, runtime 중 어디서 나는지 먼저 고정한다.
로그 위치 브라우저 콘솔과 서버 터미널 로그를 섞어 보지 않는다.
최소 변경 한 번에 한 원인만 바꿔서 해결 신호를 확인한다.

분류 루트

install -> dependency/version
dev -> port/HMR
build -> TypeScript/import
runtime -> SSR fetch/DB/Hydration