generateStaticParams

generateStaticParams 函数可与动态路由段结合使用，用于在构建时静态生成路由，而非在请求时按需生成。

// 返回一个 `params` 列表来填充 [slug] 动态段
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的多个版本
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}

// 返回一个 `params` 列表来填充 [slug] 动态段
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的多个版本
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

须知:

你可以使用 dynamicParams 段配置选项来控制当访问未通过 generateStaticParams 生成的动态段时会发生什么。

你必须从 generateStaticParams 返回一个空数组或使用 export const dynamic = 'force-static' 才能在运行时重新验证 (ISR) 路径。

在 next dev 期间，当你导航到路由时，generateStaticParams 将被调用。

在 next build 期间，generateStaticParams 会在生成相应的布局或页面之前运行。

在重新验证 (ISR) 期间，generateStaticParams 不会再次被调用。

generateStaticParams 替代了 Pages Router 中的 getStaticPaths 函数。

参数

options.params (可选)

如果路由中的多个动态段使用 generateStaticParams，则子 generateStaticParams 函数会为父级生成的每组 params 执行一次。

params 对象包含来自父级 generateStaticParams 的填充后的 params，可用于在子段中生成 params。

返回值

generateStaticParams 应返回一个对象数组，其中每个对象表示单个路由的填充后的动态段。

对象中的每个属性都是要填充到路由中的动态段。
属性名称是段的名称，属性值是该段应填充的内容。

示例路由	`generateStaticParams` 返回类型
`/product/[id]`	`{ id: string }[]`
`/products/[category]/[product]`	`{ category: string, product: string }[]`
`/products/[...slug]`	`{ slug: string[] }[]`

单一动态段

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的三个版本
// - /product/1
// - /product/2
// - /product/3
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  // ...
}

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的三个版本
// - /product/1
// - /product/2
// - /product/3
export default async function Page({ params }) {
  const { id } = await params
  // ...
}

多个动态段

export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的三个版本
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  const { category, product } = await params
  // ...
}

export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的三个版本
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({ params }) {
  const { category, product } = await params
  // ...
}

通配动态段

export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的三个版本
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string[] }>
}) {
  const { slug } = await params
  // ...
}

export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成该页面的三个版本
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

示例

静态渲染

构建时生成所有路径

要在构建时静态渲染所有路径，需向 generateStaticParams 提供完整的路径列表：

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

构建时生成部分路径

要在构建时静态渲染部分路径，并在运行时首次访问时渲染其余路径，返回部分路径列表：

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  // 在构建时渲染前 10 篇文章
  return posts.slice(0, 10).map((post) => ({
    slug: post.slug,
  }))
}

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  // 在构建时渲染前 10 篇文章
  return posts.slice(0, 10).map((post) => ({
    slug: post.slug,
  }))
}

然后，通过使用 dynamicParams 段配置选项，你可以控制当访问未通过 generateStaticParams 生成的动态段时会发生什么。

// 除前 10 篇外的所有文章将返回 404
export const dynamicParams = false

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  const topPosts = posts.slice(0, 10)

  return topPosts.map((post) => ({
    slug: post.slug,
  }))
}

// 除前 10 篇外的所有文章将返回 404
export const dynamicParams = false

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  const topPosts = posts.slice(0, 10)

  return topPosts.map((post) => ({
    slug: post.slug,
  }))
}

运行时生成所有路径

要在首次访问时静态渲染所有路径，返回一个空数组（构建时不渲染任何路径）或使用 export const dynamic = 'force-static'：

app/blog/[slug]/page.js

export async function generateStaticParams() {
  return []
}

须知：你必须始终从 generateStaticParams 返回一个数组，即使它是空的。否则，路由将被动态渲染。

app/changelog/[slug]/page.js

export const dynamic = 'force-static'

禁用未指定路径的渲染

要防止在运行时静态渲染未指定的路径，请在路由段中添加 export const dynamicParams = false 选项。使用此配置选项后，仅会提供由 generateStaticParams 提供的路径，未指定的路由将返回 404 或匹配（对于通配路由）。

路由中的多个动态段

你可以为当前布局或页面上方的动态段生成参数，但不能为下方的动态段生成参数。例如，对于 app/products/[category]/[product] 路由：

app/products/[category]/[product]/page.js 可以为两者 [category] 和 [product] 生成参数。
app/products/[category]/layout.js 只能为 [category] 生成参数。

有两种方法可以为具有多个动态段的路由生成参数：

自下而上生成参数

从子路由段生成多个动态段。

// 为 [category] 和 [product] 生成段
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
    product: product.id,
  }))
}

export default function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  // ...
}

// 为 [category] 和 [product] 生成段
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
    product: product.id,
  }))
}

export default function Page({ params }) {
  // ...
}

自上而下生成参数

先生成父段，然后使用结果生成子段。

// 为 [category] 生成段
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
  }))
}

export default function Layout({
  params,
}: {
  params: Promise<{ category: string }>
}) {
  // ...
}

// 为 [category] 生成段
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
  }))
}

export default function Layout({ params }) {
  // ...
}

子路由段的 generateStaticParams 函数会为父级 generateStaticParams 生成的每个段执行一次。

子 generateStaticParams 函数可以使用父级 generateStaticParams 函数返回的 params 动态生成自己的段。

// 使用从父段 `generateStaticParams` 函数传递的 `params` 为 [product] 生成段
export async function generateStaticParams({
  params: { category },
}: {
  params: { category: string }
}) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())

  return products.map((product) => ({
    product: product.id,
  }))
}

export default function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  // ...
}

// 使用从父段 `generateStaticParams` 函数传递的 `params` 为 [product] 生成段
export async function generateStaticParams({ params: { category } }) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())

  return products.map((product) => ({
    product: product.id,
  }))
}

export default function Page({ params }) {
  // ...
}

须知：fetch 请求会自动记忆化，在所有以 generate 为前缀的函数、布局、页面和服务器组件之间共享相同的数据。如果无法使用 fetch，可以使用 React 的 cache。

版本历史

版本	变更
`v13.0.0`	引入 `generateStaticParams`。

On this page