getStaticPaths

При экспорте функции 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

Функция getStaticPaths должна возвращать объект со следующими обязательными свойствами:

paths

Ключ paths определяет, какие пути будут предобработаны. Например, предположим, что у вас есть страница, использующая динамические маршруты под названием pages/posts/[id].js. Если вы экспортируете getStaticPaths с этой страницы и вернёте следующее для paths:

return {
  paths: [
    { params: { id: '1' }},
    {
      params: { id: '2' },
      // with i18n configured the locale for the path can be returned as well
      locale: "en",
    },
  ],
  fallback: ...
}

Тогда Next.js статически сгенерирует /posts/1 и /posts/2 во время next build используя компонент страницы в pages/posts/[id].js.

Значение для каждого объекта params должно соответствовать параметрам, используемым в имени страницы:

• Если имя страницы pages/posts/[postId]/[commentId], то params должно содержать postId и commentId.
• Если имя страницы использует маршруты с подхватом всех сегментов, такие как pages/[...slug], то params должно содержать slug (который является массивом). Если этот массив ['hello', 'world'], то Next.js статически сгенерирует страницу по адресу /hello/world.
• Если страница использует маршрут с необязательным подхватом всех сегментов, используйте null, [], undefined или false для рендеринга самого корневого маршрута. Например, если вы передадите slug: false для pages/[[...slug]], Next.js статически сгенерирует страницу /.

Строки params являются регистрозависимыми и, желательно, должны быть приведены к нормальной форме, чтобы гарантировать правильное создание путей. Например, если для параметра возвращается WoRLD, он будет соответствовать только если фактический посещенный путь WoRLD, а не world или World.

Помимо объекта params может быть возвращено поле locale, когда i18n настроен, которое настраивает язык для генерируемого пути.

fallback: false

Если fallback имеет значение false, то любые пути, не возвращенные getStaticPaths, приведут к странице 404.

Когда выполняется next build, Next.js проверит, вернула ли getStaticPaths значение fallback: false, а затем сгенерирует только пути, возвращенные getStaticPaths. Этот параметр полезен, если у вас небольшое количество путей для создания или новые данные страницы не добавляются часто. Если вы обнаружите необходимость добавить больше путей, и у вас есть fallback: false, вам нужно будет снова запустить next build, чтобы новые пути могли быть сгенерированы.

Следующий пример предобрабатывает одну страницу каждого поста в блоге, называемого pages/posts/[id].js. Список постов в блоге будет получен из CMS и возвращен функцией getStaticPaths. Затем для каждой страницы данные поста получаются из CMS с помощью getStaticProps.

function Post({ post }) {
  // Render post...
}
 
// This function gets called at build time
export async function getStaticPaths() {
  // 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 pre-render based on posts
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))
 
  // We'll pre-render only these paths at build time.
  // { fallback: false } means other routes should 404.
  return { paths, fallback: false }
}
 
// This also gets called at build time
export async function getStaticProps({ params }) {
  // params contains the post `id`.
  // If the route is like /posts/1, then params.id is 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()
 
  // Pass post data to the page via props
  return { props: { post } }
}
 
export default Post

fallback: true

Если fallback имеет значение true, поведение getStaticProps изменяется следующим образом:

• Пути, возвращенные getStaticPaths, будут отображены на HTML во время сборки getStaticProps.
• Пути, которые не были сгенерированы во время сборки, не приведут к странице 404. Вместо этого Next.js будет возвращать "fallback" версию страницы при первом запросе к такому пути. Роботы-поисковики, такие как Google, не получат fallback и вместо этого путь будет вести себя так, как описано в fallback: 'blocking'.
• Когда страница с fallback: true переходит по next/link или next/router (клиентская сторона), Next.js не будет возвращать fallback и вместо этого страница будет вести себя как в fallback: 'blocking'.
• В фоновом режиме Next.js будет статически генерировать запрашиваемый путь HTML и JSON. Это включает в себя выполнение getStaticProps.
• По завершении браузер получит JSON для сгенерированного пути. Это будет использовано для автоматического рендеринга страницы с необходимыми свойствами. С точки зрения пользователя, страница будет переключена с fallback-страницы на полную страницу.
• Одновременно Next.js добавит этот путь в список предобработанных страниц. Последующие запросы к этому же пути будут отображать сгенерированную страницу, как и другие предобработанные во время сборки.

Важно знать: fallback: true не поддерживается при использовании output: 'export'.

Когда полезно fallback: true?

fallback: true полезно, если ваше приложение имеет очень большое количество статических страниц, зависящих от данных (например, очень большой сайт электронной коммерции). Если вы хотите предобработать все страницы продуктов, сборка займет очень много времени.

Вместо этого вы можете статически сгенерировать небольшой подмножество страниц и использовать fallback: true для остальных. Когда кто-то запрашивает страницу, которая еще не сгенерирована, пользователь увидит страницу с индикатором загрузки или скелетным компонентом.

Вскоре после этого getStaticProps завершит работу, и страница будет отображена с запрошенными данными. Отныне каждый, кто запросит ту же страницу, получит статически предобработанную страницу.

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

fallback: true не будет обновлять сгенерированные страницы, для этого обратитесь к Инкрементальной статической регенерации.

fallback: 'blocking'

Если fallback имеет значение 'blocking', новые пути, не возвращенные getStaticPaths, будут ждать генерации HTML, аналогично SSR (отсюда и blocking), а затем будут кэшированы для будущих запросов, так что это произойдет только один раз на путь.

getStaticProps будет вести себя следующим образом:

• Пути, возвращенные getStaticPaths, будут отображены на HTML во время сборки getStaticProps.
• Пути, которые не были сгенерированы во время сборки, не приведут к странице 404. Вместо этого Next.js будет использовать SSR при первом запросе и вернет сгенерированную HTML.
• По завершении браузер получит HTML для сгенерированного пути. С точки зрения пользователя, произойдет переход от "браузер запрашивает страницу" к "полная страница загружена". Нет мгновенного состояния загрузки/fallback.
• Одновременно Next.js добавит этот путь в список предобработанных страниц. Последующие запросы к этому же пути будут отображать сгенерированную страницу, как и другие предобработанные во время сборки.

fallback: 'blocking' по умолчанию не будет обновлять сгенерированные страницы. Для обновления сгенерированных страниц используйте Инкрементальную статическую регенерацию в сочетании с fallback: 'blocking'.

Важно знать: fallback: 'blocking' не поддерживается при использовании output: 'export'.

Fallback-страницы

В "fallback" версии страницы:

• Свойства страницы будут пустыми.
• Используя router, вы можете определить, рендерится ли fallback. router.isFallback будет true.

Следующий пример демонстрирует использование isFallback:

import { useRouter } from 'next/router'
 
function Post({ post }) {
  const router = useRouter()
 
  // If the page is not yet generated, this will be displayed
  // initially until getStaticProps() finishes running
  if (router.isFallback) {
    return <div>Loading...</div>
  }
 
  // Render post...
}
 
// This function gets called at build time
export async function getStaticPaths() {
  return {
    // Only `/posts/1` and `/posts/2` are generated at build time
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    // Enable statically generating additional pages
    // For example: `/posts/3`
    fallback: true,
  }
}
 
// This also gets called at build time
export async function getStaticProps({ params }) {
  // params contains the post `id`.
  // If the route is like /posts/1, then params.id is 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()
 
  // Pass post data to the page via props
  return {
    props: { post },
    // Re-generate the post at most once per second
    // if a request comes in
    revalidate: 1,
  }
}
 
export default Post

История версий