Next.js Route Handler가 운영에서만 느릴 때 확인할 것

로컬에서는 되지만 운영에서는 안 된다

Next.js로 웹 애플리케이션을 만들고 배포한 후, 로컬 개발 환경에서는 문제가 없었는데 운영 환경에서만 Route Handler가 느리거나 작동하지 않는 경험을 한다. 이런 상황에서는 화면만 보고 판단하면 원인을 찾기 어렵다. 로그와 응답을 함께 봐야 한다.

웹 렌더링 문제의 핵심은 단편적인 증상이 아니라 전체 요청-응답 흐름을 추적하는 것이다. 메타데이터가 제대로 설정되어 있는지, canonical 태그가 올바른지, 빌드 결과가 예상대로 생성되었는지를 차례대로 확인해야 한다.

메타데이터부터 확인한다

Route Handler가 제대로 작동하지 않을 때, 가장 먼저 확인해야 할 것은 메타데이터와 SEO 관련 설정이다:

• 먼저 볼 값: metadata, description, canonical
• 함께 비교할 값: 로컬 개발 환경의 HTML head와 비교
• 남겨둘 기록: 빌드 로그, 응답 코드, 설정 파일

Canonical이 애매하면 다른 모든 수정이 무의미하다

canonical 태그가 틀렸다면, 다른 모든 부분을 제대로 수정해도 SEO 관점에서 문제가 해결되지 않는다. Route Handler에서 올바른 canonical을 반환하고 있는지, 빌드 시점에 제대로 주입되는지 확인해야 한다.

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

이 명령으로 실제 배포된 HTML과 로컬 빌드 결과를 직접 비교할 수 있다.

빌드 로그에서 경고를 찾는다

Route Handler가 제대로 정적 생성되지 않으면 빌드 로그에 경고나 에러가 남는다. 빌드 시에 어떤 메시지가 나타났는지, 동적 렌더링 때문에 문제가 생기지 않았는지 확인해야 한다.

단계별로 확인한다

같은 문제를 다시 만났을 때 빠르게 처리하기 위해 확인 순서를 고정한다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 빌드 로그와 응답 헤더에서 바뀐 부분을 명확히 설명할 수 있는지 확인한다
3. 공개 URL, 빌드 결과, 실제 요청 중 적어도 하나를 최종 확인한다

기록을 남긴다

Route Handler 문제를 해결한 후, 어떤 메타데이터 설정이 원인이었는지 짧게 정리해두면, 다음 번 비슷한 문제를 훨씬 빠르게 해결할 수 있다.