Next.js 배포 전 URL 슬러그 설정이 맞는지 확인하기

Next.js 프로젝트에서 동적 라우팅을 사용할 때 슬러그(slug) 생성이 제대로 되지 않으면 배포 후 404 에러가 나거나 잘못된 페이지로 이동한다. 배포 전에 슬러그 설정을 확인하는 게 중요하다.

빌드 전에 목표 명확히

어떤 패턴의 URL이 되어야 하는지 정한다. 예를 들어:

• /posts/my-first-post (슬러그 기반)
• /posts/123 (ID 기반)
• /category/tech/my-post (다중 레벨)

목표를 명확히 하고 로그에 남겨둔다.

로컬 상태 파악

현재 상태를 확인하고 정상일 때의 상태를 먼저 정해둔다. 이전 커밋에서 슬러그가 제대로 생성되었는지 확인해본다.

git log --oneline | head -5
git checkout HEAD~1  # 이전 커밋
npm run build
# 슬러그 확인

빌드 로그에서 슬러그 확인

빌드 중에 슬러그가 제대로 생성되는지 로그에서 확인한다.

npm run build

빌드 결과 있는 경로들을 확인해서 슬러그 패턴이 맞는지 본다.

설정 파일 확인

next.config.js나 getStaticPaths 함수에서 슬러그 생성 로직을 확인한다. 데이터 소스의 ID를 정확히 슬러그로 변환하는지 본다.

export async function getStaticPaths() {
  const posts = await getPosts();
  return {
    paths: posts.map(post => ({
      params: { slug: post.slug }
    })),
    fallback: false
  };
}

실제 생성된 슬러그 비교

로컬에서 생성된 슬러그와 배포 서버에서의 슬러그를 비교한다. 데이터 소스가 다르거나 인코딩이 다를 수 있다.

# 로컬에서 생성된 페이지 목록
ls .next/server/pages/posts/

# 배포 서버에서 확인 (ssh로 접속한 후)
ls /app/.next/server/pages/posts/

사용자 영향 확인

슬러그 변경으로 기존 URL이 깨지면 사용자가 북마크한 링크가 404가 된다. 이전 슬러그를 리다이렉트 해야 하는지 확인한다.

배포 후 최종 확인

배포 후에 실제 URL로 접속해본다.

curl -I https://example.com/posts/my-post

200 상태 코드가 나오면 정상이고, 301이나 404가 나오면 리다이렉트나 경로 문제가 있다는 뜻이다.

문제가 반복되면 슬러그 생성 규칙과 데이터 소스의 차이를 기록해두면 다음 배포가 빨라진다.