getStaticPaths

Если страница содержит динамические маршруты и использует getStaticProps, ей необходимо определить список путей для статического генерации.

Когда вы экспортируете функцию под названием getStaticPaths (статическое создание сайта) из страницы, использующей динамические маршруты, Next.js будет статически предварительно рендерить все пути, указанные в getStaticPaths.

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // See the "paths" section below
    ],
    fallback: true, // false or "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
}

В getStaticPaths справочнике API рассматриваются все параметры и свойства, которые можно использовать с getStaticPaths.

Когда следует использовать getStaticPaths?

Вы должны использовать getStaticPaths если вы предварительно рендерите страницы, использующие динамические маршруты, и:

• Данные поступают из headless CMS
• Данные поступают из базы данных
• Данные поступают из файловой системы
• Данные могут быть открыто кэшированы (не специфичные для пользователя)
• Страница должна быть предварительно рендерена (для SEO) и быть очень быстрой — getStaticProps генерирует HTML и JSON файлы, оба из которых могут быть кэшированы CDN для повышения производительности

Когда выполняется getStaticPaths

getStaticPaths будет выполняться только во время сборки в режиме production, она не будет вызываться во время выполнения. Вы можете проверить, что код, написанный внутри getStaticPaths, удален из клиентского пакета, с помощью этого инструмента.

Как работает getStaticProps по отношению к getStaticPaths

• getStaticProps выполняется во время next build для любого paths возвращаемого во время сборки
• getStaticProps выполняется в фоновом режиме при использовании fallback: true
• getStaticProps вызывается до начального рендеринга при использовании fallback: blocking

Где можно использовать getStaticPaths

• getStaticPaths должен использоваться с getStaticProps
• Вы не можете использовать getStaticPaths с getServerSideProps
• Вы можете экспортировать getStaticPaths из динамического маршрута, который также использует getStaticProps
• Вы не можете экспортировать getStaticPaths из файла, который не является страницей (например, из папки components)
• Вы должны экспортировать getStaticPaths как отдельную функцию, а не как свойство компонента страницы

Выполняется при каждом запросе в режиме разработки

В режиме разработки (next dev), getStaticPaths будет вызываться при каждом запросе.

Генерация путей по запросу

getStaticPaths позволяет контролировать, какие страницы генерируются во время сборки, а не по запросу с помощью fallback. Генерация большего количества страниц во время сборки приведет к более медленной сборке.

Вы можете отложить генерацию всех страниц по запросу, вернув пустой массив для paths. Это особенно полезно при развертывании вашего приложения Next.js в нескольких средах. Например, вы можете ускорить сборку, генерируя все страницы по запросу для предварительных просмотров (но не для сборок в production). Это полезно для сайтов с сотнями/тысячами статических страниц.

export async function getStaticPaths() {
  // When this is true (in preview environments) don't
  // prerender any static pages
  // (faster builds, but slower initial page load)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }
 
  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // Get the paths we want to prerender based on posts
  // In production environments, prerender all pages
  // (slower builds, but faster initial page load)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))
 
  // { fallback: false } means other routes should 404
  return { paths, fallback: false }
}