Next.js Route Handler 문제 디버깅하기

Next.js Route Handler 작업하다가 갑자기 404가 나거나 특정 경로에서만 응답이 없을 때가 있다. 검색해서 들어온 상황이라면 바로 재현 조건부터 정해야 시간을 아낄 수 있다.

Route Handler 문제는 라우팅 로직, 미들웨어, 요청 포맷 셋 중 하나에서 나오는데, 한 가지만 고집하면 시간을 낭비한다. 먼저 문제가 정확히 어디서 나는지 범위를 좁혀야 한다.

가장 먼저 할 일

Route Handler가 제대로 작동하는지 확인하려면 메타데이터와 sitemap부터 본다. 그래야 라우팅 설정이 맞는지 API 응답이 맞는지 빠르게 판단할 수 있다.

• 먼저 확인: sitemap, RSS 결과
• 비교할 값: 정상일 때의 라우팅 상태
• 남길 기록: 명령어 출력, 응답 상태코드, 수정한 설정

Route Handler 확인

API 요청이 실제로 전달되는지 커맨드라인에서 바로 테스트한다.

curl -s https://example.com/api/endpoint | grep -Ei 'title|description|canonical|og:|twitter:'
npm run build

로컬과 배포 환경에서 다르게 동작할 수 있으니, 두 곳 모두 테스트해야 한다.

빌드 결과 보기

Route Handler 문제가 반복된다면 확인 순서를 고정해야 한다. 매번 느낌으로 접근하면 같은 실수를 반복한다.

확인 순서:

1. 같은 조건에서 증상이 다시 나오는지 테스트한다
2. 로그나 응답에서 달라진 부분을 설명해본다
3. 브라우저, 빌드 결과, 실제 요청 셋 중 하나로 최종 확인한다

마무리

Route Handler 디버깅에서는 마지막에 실제 화면이나 공개 URL까지 확인해야 작업이 끝난다. 작은 기록이라도 남겨두면 다음 확인이 훨씬 빨라진다.