getStaticPaths

페이지에 동적 라우트가 있고 getStaticProps를 사용하는 경우 정적으로 생성할 경로 목록을 정의해야 합니다.

동적 경로를 사용하는 페이지에서 getStaticPaths (정적 사이트 생성) 라는 함수를 내보내면 Next.js는 getStaticPaths에 지정된 모든 경로를 정적으로 미리 렌더링합니다.

pages/repo/[name].tsx

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // 아래의 "paths" 섹션을 참조하세요.
    ],
    fallback: true, // false 또는 "blocking"
  }
}) satisfies GetStaticPaths
 
export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>
 
export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

pages/repo/[name].js

export async function getStaticPaths() {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // 아래의 "paths" 섹션을 참조하세요.
    ],
    fallback: true, // false 또는 "blocking"
  }
}
 
export async function getStaticProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}
 
export default function Page({ repo }) {
  return repo.stargazers_count
}

getStaticPaths API 레퍼런스는 getStaticPaths와 함께 사용할 수 있는 모든 매개변수와 프로퍼티를 다룹니다.

When should I use getStaticPaths?

동적 라우트를 사용하는 페이지를 정적으로 사전 렌더링할 때 다음과 같은 경우 getStaticPaths를 사용해야 합니다:

데이터가 헤드리스 CMS에서 제공되는 경우
데이터가 데이터베이스에서 제공되는 경우
데이터가 파일 시스템에서 제공되는 경우
데이터가 공개적으로 캐시될 수 있는 경우(특정 유저가 아닌)
페이지가 사전 렌더링되어야 하고(SEO를 위해) 매우 빨라야 하는 경우 - getStaticProps는 성능을 위해 CDN에서 캐시할 수 있는 HTML 및 JSON 파일을 생성합니다.

When does getStaticPaths run

getStaticPaths는 프로덕션에서 빌드하는 동안에만 실행되며 런타임 중에는 호출되지 않습니다. 이 도구 (opens in a new tab)를 사용하여 클라이언트 측 번들에서 getStaticPaths 내부에 작성된 코드가 제거되었는지 확인할 수 있습니다.

How does getStaticProps run with regards to getStaticPaths

getStaticProps는 next build 도중 반환된 모든 paths에 대해 빌드 중 실행됩니다.
getStaticProps는 fallback: true를 사용할 때 백그라운드에서 실행됩니다.
getStaticProps는 fallback: blocking을 사용할 때 초기 렌더링 전에 호출됩니다.

Where can I use getStaticPaths

getStaticPaths는 반드시 getStaticProps와 함께 사용해야 합니다.
getStaticPaths는 getServerSideProps와 함께 사용할 수 없습니다.
getStaticPaths는 페이지가 아닌 파일(예: 컴포넌트 폴더)에서 익스포트 할 수 없습니다.
getStaticPaths는 페이지 컴포넌트의 프로퍼티가 아닌 독립형 함수로 내보내야 합니다.

Runs on every request in development

개발 단계 (next dev)에서는 모든 요청에 대해 getStaticPaths가 호출됩니다.

Generating paths on-demand

getStaticPaths를 사용하면 fallback을 사용하여 온 디맨드 대신 빌드 중에 생성할 페이지를 제어할 수 있습니다. 빌드 중에 더 많은 페이지를 생성하면 빌드 속도가 느려집니다.

path에 대한 빈 배열을 반환하여 모든 페이지 생성을 온 디맨드 방식으로 연기할 수 있습니다. 이 기능은 여러 환경에 Next.js 애플리케이션을 배포할 때 특히 유용할 수 있습니다. 예를 들어 모든 페이지를 미리 보기용으로 온 디맨드 생성하여 빌드 속도를 높일 수 있습니다(프로덕션 빌드 제외). 이는 수백/수천 개의 정적 페이지가 있는 사이트에 유용합니다.

pages/posts/[id].js

export async function getStaticPaths() {
  // 이 경우(미리보기 환경에서) 정적 페이지를
  // 프리 렌더링하지 마십시오.
  // (빌드는 빨라지지만 초기 페이지 로드는 느려짐)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }
 
  // 외부 API 엔드포인트를 호출하여 포스트 가져오기
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // posts를 기반으로 프리 렌더링할 경로 가져오기
  // 프로덕션 환경에서는 모든 페이지를 프리 렌더링합니다.
  // (빌드 속도는 느려지지만 초기 페이지 로드 속도는 빨라짐)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))
 
  // { fallback: false } 는 다른 경로가 404임을 의미합니다.
  return { paths, fallback: false }
}

Get Static Props Forms and Mutations