Next.js Route Handler 배포 전 확인 체크리스트

Next.js Route Handler는 API 엔드포인트로 동작하는데, 로컬에서는 잘 작동하던 게 배포 후 다르게 작동하는 경우가 있다. 원인은 보통 환경 설정이나 빌드 방식의 차이에 있다.

Route Handler가 제대로 빌드되었는지 확인

먼저 전체 빌드를 실행하고 에러가 없는지 확인한다.

npm run build

빌드가 성공하면 app 디렉토리의 route 파일들이 정상 컴파일되었다는 뜻이다.

로컬에서 Route Handler 테스트

개발 서버를 실행하고 직접 요청을 보내본다.

npm run dev
# 다른 터미널에서
curl -i https://localhost:3000/api/items?page=1

Status code, 응답 헤더, 응답 body를 모두 확인한다. 특히 CORS 헤더나 content-type이 올바른지 확인해야 한다.

배포 전 sitemap과 RSS 확인

Route Handler가 정적 콘텐츠(sitemap, RSS)를 생성하는 경우, 빌드 후 파일이 제대로 생성되었는지 확인한다.

환경 변수 확인

로컬과 운영 환경의 환경 변수가 다르면 Route Handler 동작이 달라질 수 있다. 배포하기 전에 환경 변수 목록을 정리해둔다.

HTML head 메타데이터 확인

Route Handler가 페이지 메타데이터를 수정하는 경우(메타데이터 엔드포인트), 배포 후 SEO 메타 태그들을 확인한다.

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'

배포 후 최종 검증

배포 후에는 실제 Route Handler 엔드포인트에 요청을 보내본다. 로컬과 운영 환경의 응답이 같은지 비교한다.

작은 확인들을 기록해두면 다음 배포가 훨씬 빨라진다.