generateStaticParams로 동적 주소 미리 만들기

자주 쓰는 동적 경로를 빌드 때 준비해

generateStaticParams는 App Router에서 Pages Router의 getStaticPaths 역할을 해. 동적 라우트에서 함수를 내보내고 미리 만들 parameter 목록을 반환하면, Next.js가 빌드할 때 각 경로의 정적 HTML을 생성해.

목록에 없다고 기본 404는 아니야

반환 목록에 없는 주소는 기본적으로 첫 요청 때 렌더링한 뒤 캐시해. 알려지지 않은 slug를 허용하지 않으려면 export const dynamicParams = false를 함께 선언해야 해. 미리 만들 목록과 허용 목록은 서로 다른 결정이야.

중첩 경로는 필요한 모든 값을 반환해

[category]/[product]처럼 동적 구간이 여러 개라면 각 객체에 두 구간의 값을 모두 채워. 함수는 빌드 중 실행돼. 가능한 모든 조합을 열거할 의무는 없고, 첫 방문을 빠르게 만들 가치가 있는 경로만 골라도 돼.

빌드 크기와 첫 요청 비용을 교환해

목록이 길수록 배포 빌드는 느리고 산출물은 커지지만 첫 방문은 빨라져. 트래픽이 거의 없는 수십만 경로를 전부 미리 만드는 대신 인기 경로만 준비하는 식으로 실제 사용량에 맞춰.

분석에서 첫 방문이 많은 동적 경로를 골라 generateStaticParams 목록으로 만들어. 빌드 시간, 산출물 크기, 목록 밖 경로의 첫 응답을 함께 재서 prebuild 경계를 조정해. 콘텐츠가 삭제됐을 때 옛 정적 경로가 어떻게 404로 바뀌는지도 배포 흐름에 포함해.

모든 경로를 미리 만들면 런타임 비용은 줄지만 배포가 데이터 양에 묶여 느려져. 아무것도 만들지 않으면 긴 꼬리 첫 방문자가 비용을 낸다. 인기 경로를 미리 만들고 나머지를 요청 시 생성하는 혼합이 많은 제품에서 더 현실적이야.

인기 slug 일부만 반환해 build가 만든 페이지 수와 시간을 기록하고, 목록 밖 slug의 첫·두 번째 요청을 비교해 on-demand 캐시를 확인해. dynamicParams = false를 켰을 때 같은 주소가 404가 되는지와 중첩 params가 모두 채워지는지도 시험해. 미리 만든 경로의 수가 데이터 증가와 함께 어떻게 변하는지 추세를 봐. 오늘 빠른 빌드도 글이 열 배가 되면 배포 병목이 될 수 있어. 목록 선택 규칙과 상한을 코드로 남기면 성장이 곧 사고가 되지 않아.

Code

블로그 글 미리 빌드하기·tsx

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const slugs = await getAllPostSlugs();
  return slugs.map((slug) => ({ slug }));
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await fetchPost(slug);
  return <article dangerouslySetInnerHTML={{ __html: post.html }} />;
}

목록 밖 경로를 404로 고정하기·tsx

export const dynamicParams = false; // generateStaticParams 목록 밖 slug는 404

export async function generateStaticParams() {
  return [{ slug: 'hello' }, { slug: 'world' }];
}

2단계 동적 경로·tsx

// app/[locale]/blog/[slug]/page.tsx
export async function generateStaticParams() {
  return [
    { locale: 'en', slug: 'hello' },
    { locale: 'ko', slug: 'hello' },
    { locale: 'en', slug: 'world' },
  ];
}

자주 쓰는 동적 경로를 빌드 때 준비해

목록에 없다고 기본 404는 아니야

중첩 경로는 필요한 모든 값을 반환해

빌드 크기와 첫 요청 비용을 교환해

Code

External links

Exercise

Progress

댓글 0