Next.js 15 마이그레이션과 404 트러블슈팅 가이드

Next.js 15으로 업데이트하면서 발생할 수 있는 주요 변경 사항과, 특히 정적 내보내기(Static Export) 환경에서 발생하기 쉬운 404 에러 해결 방법을 공유합니다.

1. 비동기 Params 처리 (Breaking Change)

Next.js 15의 가장 큰 변화 중 하나는 params와 searchParams가 더 이상 동기적으로 접근 가능한 객체가 아니라는 점입니다. 이제는 Promise로 제공되므로 반드시 await를 사용해야 합니다.

잘못된 예 (동기 접근)

export default function Page({ params }) {
  const slug = params.slug; // 런타임 에러 발생
  return <div>{slug}</div>;
}

올바른 예 (비동기 접근)

export default async function Page({ params }) {
  const { slug } = await params;
  return <div>{slug}</div>;
}

이 처리가 누락되면 로컬 개발 환경이나 서버 사이드 렌더링 시 페이지가 정상적으로 로드되지 않고 404 또는 500 에러를 반환하게 됩니다.

2. 정적 내보내기(Static Export)에서의 404 이슈

output: 'export' 설정을 사용하는 경우, 모든 동적 라우트는 generateStaticParams를 통해 사전에 빌드되어야 합니다.

주요 체크리스트:

• 1페이지 경로: 페이지네이션 구현 시 1페이지는 /1이 아닌 기본 경로(/)를 사용해야 합니다.
• Trailing Slash: next.config.js의 trailingSlash 설정이 true라면 모든 링크 뒤에 /를 붙여 리다이렉트와 404를 방지해야 합니다.
• 동적 카테고리: 새로 추가된 카테고리에 대해서도 generateStaticParams가 경로를 생성할 수 있도록 리스트를 동적으로 관리해야 합니다.

3. 요약

Next.js 15은 더 엄격한 비동기 처리를 요구하며, 특히 정적 배포 환경에서는 경로 생성 로직의 세밀한 조정이 필요합니다. 이번 마이그레이션을 통해 더욱 안정적이고 빠른 블로그 시스템을 구축할 수 있었습니다.