getStaticPaths

Если страница использует Динамические маршруты (Dynamic Routes) и 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',
        },
      }, // См. раздел "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
}

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
}

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

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

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

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

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

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

Как выполняется getStaticProps относительно getStaticPaths

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

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

getStaticPaths обязательно должен использоваться с getStaticProps
Нельзя использовать getStaticPaths с getServerSideProps
Можно экспортировать getStaticPaths из Динамического маршрута (Dynamic Route), который также использует getStaticProps
Нельзя экспортировать getStaticPaths из файла, не являющегося страницей (например, из папки components)
getStaticPaths должен экспортироваться как отдельная функция, а не как свойство компонента страницы

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

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

Генерация путей по требованию

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

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

pages/posts/[id].js

export async function getStaticPaths() {
  // Когда это true (в средах превью), не
  // предварительно рендерить статические страницы
  // (быстрее сборки, но медленнее первоначальная загрузка страницы)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // Вызов внешнего API для получения постов
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Получение путей для предварительного рендеринга на основе постов
  // В production средах предварительно рендерить все страницы
  // (медленнее сборки, но быстрее первоначальная загрузка страницы)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } означает, что другие маршруты должны возвращать 404
  return { paths, fallback: false }
}