#29. generateStaticParams / dynamicParams

generateStaticParams / dynamicParams 정리 (App Router)

1) 언제 필요한가요?

App Router에서 폴더명을 대괄호로 감싸면 동적 세그먼트(Dynamic Segment)를 만들 수 있습니다.

• app/blog/[slug]/page.tsx → /blog/a, /blog/b 처럼 slug가 바뀌는 라우트
• app/shop/[...slug]/page.tsx → /shop/a/b/c 처럼 catch-all 라우트 (slug는 배열)
• app/shop/[[...slug]]/page.tsx → /shop도 매칭되는 optional catch-all (slug가 undefined 가능) Next.js

문제는 “가능한 slug가 몇 개인지 / 언제 알 수 있는지”입니다.
이때 등장하는 것이 generateStaticParams(정적으로 미리 만들 목록)와 dynamicParams(목록에 없는 값이 오면 어떻게 할지)입니다.

---

2) generateStaticParams란?

generateStaticParams는 동적 라우트에서 빌드 시점에 미리 생성할 params 목록을 반환하는 함수입니다. 즉, 요청 시점(on-demand)이 아니라 build 단계에서 라우트를 정적으로 생성할 수 있습니다. Next.js

• page.tsx, layout.tsx, route.ts에서 사용할 수 있습니다. Next.js
• 반드시 배열(Array) 을 반환해야 하며, 비어 있어도 [] 형태로 반환해야 합니다. Next.js

기본 예시: [slug]를 빌드 때 일부/전체 생성

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await fetch("https://.../posts").then(r => r.json());

  return posts.map((post: any) => ({
    slug: post.slug,
  }));
}

 

위처럼 반환한 { slug } 목록만큼 여러 버전의 페이지가 정적으로 생성됩니다. Next.js

---

3) “전부 미리” vs “일부만 미리” 전략

A. 모든 경로를 빌드 시점에 생성(SSG 성격)

가능한 slug가 많지 않고(수백~수천), 빌드 시간 부담이 크지 않을 때 적합합니다. Next.js

B. 일부(상위 N개)만 빌드 시점에 생성 + 나머지는 런타임에서 처리

Next.js 공식 예시처럼, 상위 10개만 미리 만들고 나머지는 정책으로 처리할 수 있습니다. Next.js+1

// 빌드 시 상위 10개만 생성
export async function generateStaticParams() {
  const posts = await fetch("https://.../posts").then(r => r.json());
  return posts.slice(0, 10).map((p: any) => ({ slug: p.slug }));
}

 

여기서 “나머지 slug가 들어오면 어떻게 할지”를 결정하는 것이 dynamicParams입니다. Next.js+1

---

4) dynamicParams란?

dynamicParams는 generateStaticParams로 생성되지 않은 동적 세그먼트가 요청될 때의 동작을 정하는 옵션입니다. Next.js

 

// app/blog/[slug]/page.tsx
export const dynamicParams = true; // true | false

• true(기본값): 목록에 없는 slug도 요청 시점에 on-demand로 생성합니다. Next.js
• false: 목록에 없는 slug는 404를 반환합니다. Next.js+1

또한 이 옵션은 Pages Router의 getStaticPaths에서 쓰던 fallback(true/false/blocking)을 대체한다고 문서에 명시되어 있습니다. Next.js

---

5) 실전에서 어떻게 조합하나요?

케이스 1) “목록에 있는 것만 허용” (엄격한 라우트)

• 예: /category/[code]에서 code가 DB에 정의된 몇 개 뿐
• 목적: 이상한 URL 접근 시 “조용히 만들어주지 말고 404로 끊기”

export const dynamicParams = false;
export async function generateStaticParams() {
  return [{ code: "A" }, { code: "B" }];
}

→ A/B만 열리고 나머지는 404 Next.js+1

케이스 2) “상위 N개만 미리 + 나머지는 필요할 때 생성” (롱테일 대응)

• 예: 블로그 글이 10만 개라 빌드 때 전부 만들기 부담
• 상위 인기글만 선빌드, 나머지는 방문 시 생성

 

export const dynamicParams = true; // 기본값
export async function generateStaticParams() {
  // 상위 100개만 빌드 시 생성
  return top100.map(p => ({ slug: p.slug }));
}

→ 100개는 빠르게, 나머지는 방문 시 생성 Next.js+1

케이스 3) “빌드 때는 아무 것도 안 만들고, 전부 첫 방문에 생성”

generateStaticParams에서 **빈 배열 []**을 반환하면, “빌드 시점에 생성 없음” + “첫 방문에 정적 생성” 같은 형태로 운영할 수 있습니다. 문서에서도 “빈 배열을 반환하거나 dynamic = 'force-static'을 사용하라”고 안내합니다. Next.js+1

 

export async function generateStaticParams() {
  return [];
}

 

---

6) 자주 하는 실수/주의사항

• generateStaticParams는 'use client' 파일에서 사용할 수 없습니다. (Server 쪽 기능) Next.js
• 하위 세그먼트(예: /[category]/[slug])에서 여러 generateStaticParams가 있으면, 부모가 만든 params 조합마다 자식이 실행됩니다. (즉, 조합 수가 늘면 빌드 작업도 커집니다.) Next.js
• 개발 모드(next dev)에서는 라우트 이동 시 generateStaticParams가 호출될 수 있어, 운영과 체감이 다를 수 있습니다. Next.js

---

7) 한 줄 결론

• generateStaticParams = 동적 라우트에서 “미리 만들 params 목록”을 정의하는 함수 Next.js
• dynamicParams = 목록에 없는 params가 들어오면 “만들어줄지(on-demand) / 404로 막을지” 결정하는 스위치 Next.js