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',
        },
      }, // См. раздел "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 из Динамического маршрута, который также использует 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 }
}