정적 데이터 생성 (SSG)

Next.js는 높은 성능을 위해 다양한 렌더링 전략을 제공합니다.

그중 대표가 정적 사이트 생성(Static Site Generation, SSG)입니다.

SSG는 빌드 시점에 페이지를 HTML로 미리 만들어 두고, 요청 시 서버 렌더링 없이 즉시 전달하는 방식입니다.

이 접근은 로딩 속도를 크게 개선하고, CDN을 통해 전 세계 사용자에게 빠르게 콘텐츠를 제공할 수 있게 해줍니다.

이 절에서는 Next.js App Router에서 SSG를 구현하는 방법과 그 이점, 그리고 어떤 상황에서 SSG를 선택해야 하는지 자세히 알아보겠습니다.

실습은 6장 1절의 [email protected]와 http://localhost:4000을 사용합니다. Next.js 16의 cacheComponents는 활성화하지 않습니다.

포트 정책은 4000=Mock API, 4100=별도 백엔드/실시간 서버로 분리해 두면 병행 실습 시 충돌을 줄일 수 있습니다.

SSG란 무엇인가요?

정적 사이트 생성(SSG)은 초기 화면의 HTML·RSC 결과를 빌드 타임(Build Time)에 미리 만드는 방식입니다. 이후 클라이언트 상호작용이나 데이터 갱신까지 빌드 시점에 고정하는 것은 아닙니다.

생성한 결과를 Next.js 서버나 CDN에서 재사용하므로, 캐시된 경로의 요청마다 원본 데이터를 읽고 화면을 다시 계산하는 비용을 줄입니다.

• 빠른 응답: 페이지 요청 시 미리 생성된 HTML 파일이 반환되므로, 요청 시점의 데이터 페칭이나 서버 렌더링 비용이 없습니다.
• 향상된 SEO: 검색 엔진 크롤러가 미리 생성된 HTML 콘텐츠를 쉽게 읽고 색인화할 수 있어 검색 엔진 최적화에 유리합니다.
• 비용 효율성: 서버 부하가 거의 없거나 낮기 때문에, 트래픽이 많아도 서버 비용을 절감할 수 있습니다.
• 안정성: 빌드 시 생성된 파일이므로 런타임 에러의 가능성이 적고, 가용성은 CDN·서버·배포 구성에 달려 있습니다.

• 변화가 적은 데이터: 블로그 게시물, 문서, 상품 목록(재고 변동이 적은), 포트폴리오 사이트 등 콘텐츠가 자주 업데이트되지 않는 경우.
• 모든 사용자에게 동일한 콘텐츠: 사용자별 맞춤형 콘텐츠가 필요하지 않고, 모든 사용자에게 동일한 페이지를 보여줄 때.
• 높은 SEO 요구사항: 검색 엔진 노출이 중요한 경우.

SSG는 "미리 만들 수 있는가"와 "얼마나 자주 바뀌는가"를 함께 판단해야 합니다.

App Router에서 SSG 구현하기

동적 세그먼트가 없는 경로도 정적으로 프리렌더할 수 있습니다. 이 실습은 동적 라우트([slug], [id] 등)에서 generateStaticParams로 미리 만들 파라미터 목록을 정합니다. 이 함수만 추가한다고 요청 시점 API를 쓰는 라우트까지 정적으로 바뀌지는 않습니다.

generateStaticParams 함수는 프로덕션 빌드에서 페이지가 생성되기 전에 실행되며, 해당 동적 라우트에서 어떤 파라미터 값들을 미리 생성할지 Next.js에 알려줍니다.

개발 서버에서는 해당 라우트로 이동할 때 호출되므로, 프로덕션 빌드에서만 실행되는 함수로 오해하면 안 됩니다.

이전 5장 1절에서 만들었던 src/app/posts/[id]/page.tsx 예제를 사용하여, 이 게시물 상세 페이지들을 빌드 시점에 미리 생성하도록 설정해 보겠습니다.

import Link from 'next/link';

interface PostDetailPageProps {
  params: Promise<{
    id: string; // URL에서 추출될 게시물 ID
  }>;
}

interface Post {
  id: number;
  title: string;
  body: string;
}

// 1. 특정 게시물 데이터를 가져오는 함수 (서버 컴포넌트 내부에서 사용)
async function getPost(id: string): Promise<Post> {
  const res = await fetch(`http://localhost:4000/posts/${id}`);
  if (!res.ok) {
    // 실제 서비스에서는 적절한 에러 처리 또는 notFound() 호출
    throw new Error(`Failed to fetch post with ID: ${id}`);
  }
  return res.json();
}

// 2. generateStaticParams 함수 정의: 미리 생성할 경로들을 결정합니다.
// 이 함수는 'app' 폴더 내의 동적 라우트 페이지/레이아웃에서만 사용할 수 있습니다.
export async function generateStaticParams() {
  // 프로덕션 빌드 전 또는 개발 중 이 라우트로 이동할 때 호출됩니다.
  console.log('generateStaticParams 🚀: fetching all posts IDs for SSG');
  const res = await fetch('http://localhost:4000/posts?_limit=20');
  const payload = await res.json();
  const posts: Post[] = payload;

  // 모든 게시물의 ID를 추출하여 { id: string } 형태의 객체 배열로 반환합니다.
  // Next.js는 이 배열의 각 객체에 대해 해당 페이지를 미리 생성합니다.
  return posts.map((post) => ({
    id: post.id.toString(), // params의 값은 항상 문자열이어야 합니다.
  }));
}

// 3. 페이지 컴포넌트: params를 받아 데이터를 렌더링합니다.
export default async function PostDetailPage({ params }: PostDetailPageProps) {
  const { id } = await params;
  const post = await getPost(id); // getStaticProps의 context.params와 유사하게 작동

  return (
    <div style={{ padding: '20px', maxWidth: '800px', margin: '0 auto', border: '1px solid #eee', borderRadius: '8px', boxShadow: '0 2px 5px rgba(0,0,0,0.05)' }}>
      <h1 style={{ color: '#333', marginBottom: '15px' }}>{post.title}</h1>
      <p style={{ lineHeight: '1.6', color: '#555' }}>{post.body}</p>
      <div style={{ marginTop: '30px', paddingTop: '15px', borderTop: '1px dashed #eee' }}>
        <Link href="/posts" style={{ color: '#0070f3', textDecoration: 'none' }}>
          &larr; 목록으로 돌아가기
        </Link>
      </div>
    </div>
  );
}

반환 목록 밖의 파라미터는 dynamicParams 정책에 따릅니다. 경로 목록을 미리 정하는 일과 API의 데이터를 저장하는 일은 다릅니다. getPost는 선택된 id의 본문을 가져오고, generateStaticParams는 미리 만들 경로의 문자열 id를 반환합니다. 목록의 길이가 페이지에 표시할 게시물 수나 DB의 총 개수를 대신하지는 않습니다. 원문의 getPost는 HTTP 실패를 일반 오류로 던지며, 존재하지 않는 게시물을 notFound()로 처리하는 구현은 없습니다.

npm run build
# 또는
yarn build

npm run start
# 또는
yarn start

generateStaticParams의 작동 방식

• 호출 시점: 프로덕션 빌드에서는 대응하는 페이지나 레이아웃이 생성되기 전에 실행됩니다. 개발 서버에서는 해당 라우트로 이동할 때 호출됩니다.
• 재검증과의 관계: ISR로 페이지를 다시 검증할 때 generateStaticParams가 다시 호출되지는 않습니다. 배포 뒤 새 경로를 허용할지는 dynamicParams와 반환 목록을 함께 보고 결정해야 합니다.
• 데이터 페칭: generateStaticParams 내부에서도 fetch와 같은 비동기 데이터 페칭 함수를 사용할 수 있습니다. 이 결과는 미리 생성할 경로 목록을 정하는 데 사용됩니다.
• 반환값: 함수는 { paramName: value } 형태의 객체 배열을 반환해야 합니다. paramName은 동적 라우트 폴더의 대괄호 안 이름([id]의 id)과 정확히 일치해야 하며, 단일 세그먼트의 value는 string 타입입니다. Catch-all은 아래처럼 문자열 배열을 사용합니다.
• Catch-all 세그먼트 ([...slug]): Catch-all 세그먼트의 경우, slug: ['path', 'to', 'document']와 같이 문자열 배열을 반환해야 합니다.

  export async function generateStaticParams() {
    return [{ slug: ['a', 'b'] }, { slug: ['c'] }];
  }

• 성능 최적화: generateStaticParams에서 반환하는 경로의 수가 많을수록 빌드 시간이 길어집니다. 따라서 실제 필요한 페이지만 SSG하거나, 중요한 페이지 위주로 SSG하고 나머지는 CSR 또는 SSR로 처리하는 전략을 고려할 수 있습니다.

빌드 때 읽은 상품 가격을 남겨두기

앞 절에서 준비한 상품을 SSG 페이지로 표시해 보겠습니다. 아래 파일에는 요청 정보를 읽는 API나 재검증 설정이 없습니다. 이 조건에서는 기본 fetch가 빌드 때 원본을 읽고, 만들어진 HTML·RSC 라우트 결과가 이후 요청에 재사용됩니다. 데이터 응답을 force-cache로 저장하는 설명과는 구분합니다.

interface Product {
  id: number;
  name: string;
  price: number;
}

async function getProduct(): Promise<Product> {
  const res = await fetch('http://localhost:4000/products/1');
  if (!res.ok) {
    throw new Error(`상품 조회 실패: ${res.status}`);
  }
  return res.json();
}

export default async function SsgProductPage() {
  const product = await getProduct();

  return (
    <main>
      <h1>SSG 상품 가격</h1>
      <p>{product.name} (상품 {product.id})</p>
      <p>가격: {product.price.toLocaleString('ko-KR')}원</p>
    </main>
  );
}

원본 가격이 299000일 때 빌드에 성공했다면 그 빌드의 SSG 페이지에는 299,000원이 남습니다. 원본만 349000으로 바꾸고 새 요청을 보내도 같은 빌드의 정적 결과는 바뀌지 않습니다. 새 빌드에 성공해야 새 원본을 읽은 결과를 만들 수 있습니다.

Mock 서버가 꺼졌거나 상품 조회에서 오류가 던져지면 이 페이지의 빌드도 실패할 수 있습니다. 성공한 빌드가 없는 상태를 “이전 가격을 계속 보여주는 SSG”로 해석하지 않습니다. Product는 TypeScript의 타입이며 API 응답의 필드·자료형을 실행 중에 검사하는 코드는 아닙니다.

다른 경로로 판단해 보기

Mock에는 게시물 1·2·10이 있지만 미리 생성할 목록은 [{ id: '1' }, { id: '2' }]라고 가정합니다. cookies·headers 같은 요청 시점 의존 API를 쓰지 않는 이 실습 모델에서 무엇을 빌드 전에 알고, 무엇을 /posts/10 요청 때 판단해야 할까요? 기본 dynamicParams와 false를 구분해 답해 보세요. 아래 코드는 두 정책 중 false를 선택할 때 추가하는 선언이며 원 페이지의 필수 줄은 아닙니다.

export const dynamicParams = false;

이 파일만 만든 뒤 곧바로 비교를 시작하지 말고, 다음 절의 SSR·ISR 파일과 관찰 순서까지 준비합니다. 세 라우트가 같은 원본을 읽어야 생성 시점의 차이를 볼 수 있습니다.

SSG와 ISR

generateStaticParams를 통해 SSG된 페이지는 기본적으로 빌드 시점에 고정됩니다.

하지만 fetch의 next.revalidate 옵션을 사용하면 캐시가 지정한 시간보다 오래된 뒤 들어온 요청을 계기로 백그라운드 재검증을 수행해 새 데이터를 반영할 수 있습니다.

이것이 바로 ISR(Incremental Static Regeneration)입니다.

SSG와 ISR은 모두 정적 응답의 장점을 활용하지만, 데이터가 얼마나 자주 바뀌는지에 따라 선택 기준이 달라집니다.

아래는 재검증 설정에 집중한 발췌입니다. Product 타입·일부 오류 처리·페이지 반환 JSX가 생략되어 있으므로 그대로 실행하는 완성 파일은 아닙니다.

// ... (다른 코드 생략) ...

async function getProduct(id: string): Promise<Product> {
  const res = await fetch(`http://localhost:4000/products/${id}`, {
    // 이 페이지는 SSG로 미리 생성되지만, 캐시가 60초 이상 지난 뒤
    // 새 요청이 들어오면 백그라운드 재검증을 시작할 수 있습니다.
    next: { revalidate: 60 },
  });
  if (!res.ok) { /* ... */ }
  return res.json();
}

export async function generateStaticParams() {
  // 빌드 시점에 생성할 모든 상품 ID를 반환
  // ... (모든 상품 ID를 가져오는 로직) ...
  return [{ id: 'product-1' }, { id: 'product-2' }];
}

export default async function ProductDetailPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);
  // ... (상품 정보 렌더링) ...
}

위 예시에서 generateStaticParams는 프로덕션 빌드 때 미리 생성할 경로를 정합니다.

fetch의 next: { revalidate: 60 }는 캐시가 60초 이상 지난 뒤 새 요청이 들어오면 재검증할 수 있게 하지만, 이 과정에서 generateStaticParams를 다시 호출하지는 않습니다.