Next.js Route Handler 배포 후 화면 차이 해결

Next.js 프로젝트를 배포했을 때 로컬에서는 완벽했던 라우팅이 운영 환경에서는 이상하게 작동할 때가 있다. 특히 동적 라우트나 캐싱 설정이 있을 때 문제가 두드러진다.

첫 번째: Sitemap과 RSS 확인

Route Handler 문제는 먼저 정적 자산부터 확인하면 빠르다:

curl -s https://example.com/sitemap.xml
curl -s https://example.com/feed.xml

Sitemap이나 RSS가 제대로 생성되지 않았다면 Route Handler가 제대로 작동하지 않는다는 뜻이다. 특히 동적 콘텐츠를 기반으로 sitemap을 생성하는 경우 데이터베이스 연결을 먼저 확인해야 한다.

빌드 로그 확인

배포 과정의 빌드 로그를 자세히 봐야 한다:

npm run build

로그에서 Route Handler 또는 API routes가 몇 개 생성되었는지, 에러나 경고가 있는지 확인하자. 만약 [dynamicRoute] 같은 동적 라우트가 제대로 감지되지 않으면 파일 이름을 다시 확인해야 한다.

Canonical과 메타데이터

SEO 메타데이터가 제대로 설정되었는지 확인하는 것도 중요하다:

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

각 페이지의 canonical URL이 올바른지, Open Graph 태그가 있는지 확인하자. 만약 canonical이 없거나 잘못 설정되면 검색 엔진이 같은 콘텐츠를 중복으로 인식할 수 있다.

동적 라우트 테스트

Route Handler에서 동적 파라미터를 사용한다면 실제로 작동하는지 여러 케이스로 테스트해야 한다:

// app/api/posts/[id]/route.ts
export async function GET(request: Request, { params }: { params: { id: string } }) {
  const post = await getPost(params.id);
  return Response.json(post);
}

/api/posts/123, /api/posts/abc, /api/posts/invalid 같은 다양한 입력값으로 테스트해보자.

캐싱 설정 점검

Next.js는 기본적으로 Route Handler의 응답을 캐싱한다. 이것이 예상과 다르게 작동할 수 있다:

export async function GET() {
  // 기본: 캐시됨
  const data = await fetchData();
  return Response.json(data);
}

export async function GET() {
  // 캐시 비활성화
  const data = await fetchData();
  return Response.json(data, {
    headers: {
      'Cache-Control': 'no-store',
    },
  });
}

배포 후 확인

1. 화면에서 실제로 콘텐츠가 로드되는지 확인한다.
2. 빌드 로그와 런타임 로그를 함께 본다. 빌드는 성공했지만 런타임에 Route Handler가 실패할 수도 있다.
3. 공개 URL에서 API 응답을 직접 확인한다.

재배포

만약 캐싱 문제라면 재배포만으로 해결될 수 있다. 하지만 코드 문제라면 먼저 원인을 찾아야 한다:

1. 로컬에서 같은 환경으로 재현할 수 있는지 확인한다.
2. 배포 환경의 환경 변수가 올바른지 본다.
3. 데이터베이스나 외부 API 연결 상태를 확인한다.

Route Handler 문제는 대부분 빌드와 런타임의 차이에서 나온다. 작은 확인들을 쌓으면 나중에 같은 문제를 훨씬 빨리 처리할 수 있다.