generateStaticParams로 정적 생성했는데 새 글이 404가 뜨는 이유

문제 발생

블로그 상세 페이지에 generateStaticParams로 빌드 시점의 게시글 목록을 정적 생성했는데, 배포 이후에 새로 작성한 글에 접근하면 404가 떴습니다.

export async function generateStaticParams() {
  const posts = await getPublishedPosts(); // 빌드 시점 데이터
  return posts.map((post) => ({ slug: post.slug }));
}

원인 분석

generateStaticParams는 빌드 시점에 실행되어, 그 시점에 반환한 파라미터 목록만큼만 정적 페이지를 미리 만듭니다. 빌드 이후 데이터베이스에 추가된 새 글은 이 목록에 포함되지 않았으므로 정적 페이지가 없습니다.

이때 실제 동작은 dynamicParams 옵션 값에 따라 달라집니다. 기본값은 true인데, 이 경우 목록에 없는 파라미터로 요청이 오면 Next.js가 그 요청 시점에 서버에서 페이지를 생성하려고 시도합니다. 만약 페이지 컴포넌트 안에서 데이터를 못 찾으면 명시적으로 notFound()를 호출하는 로직이 있다면 그게 404의 진짜 원인일 수 있고, dynamicParams를 false로 명시해뒀다면 목록에 없는 파라미터는 무조건 404를 반환하도록 강제됩니다.

해결 방안

1. 새로 추가되는 데이터가 배포 사이에도 계속 생긴다면(블로그, 커뮤니티 게시글 등), dynamicParams를 기본값(true)으로 두거나 명시적으로 true로 설정해 목록에 없는 요청도 서버에서 즉시 렌더링되도록 합니다.

export const dynamicParams = true; // 기본값이지만 의도를 명시

2. 그렇게 하면 첫 요청 시 서버에서 렌더링하고, 이후 캐시 전략("use cache", ISR 등)에 따라 결과를 캐싱할지 결정할 수 있습니다.
3. 반대로 콘텐츠가 빌드 시점에 완전히 고정되는 경우(예: 문서 사이트의 정해진 페이지 목록)라면 dynamicParams = false로 두어, 목록에 없는 잘못된 경로는 확실히 404가 되도록 강제하는 것이 오히려 안전합니다 — 오타난 URL이 서버에서 불필요한 렌더링을 시도하지 않게 막아줍니다.
4. 페이지 컴포넌트 안에서 데이터가 없을 때 notFound()를 호출하는 로직과, generateStaticParams/dynamicParams 설정을 같이 놓고 어느 쪽이 실제로 404를 만들고 있는지 구분해서 디버깅합니다.

공식 문서

• Next.js Docs: generateStaticParams

dynamicParams의 기본값과 동작은 Next.js 버전에 따라 달라질 수 있으므로 실제 설치 버전 문서를 확인합니다.