generateStaticParams

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

app/blog/[slug]/page.js

// 返回一个 `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 function Page({ params }) {
  const { slug } = params
  // ...
}

须知

您可以使用 dynamicParams 段配置选项来控制访问未通过 generateStaticParams 生成的动态段时的行为。

在 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 function Page({ params }: { params: { id: string } }) {
  const { id } = 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 function Page({
  params,
}: {
  params: { category: string; product: string }
}) {
  const { category, product } = 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 function Page({ params }: { params: { slug: string[] } }) {
  const { slug } = params
  // ...
}

示例

多动态段路由

您可以为当前布局或页面上方的动态段生成参数，但不能为下方的段生成。例如，对于 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: { category: string; product: 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 }: { params: { category: string } }) {
  // ...
}

子路由段的 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: { category: string; product: string }
}) {
  // ...
}

须知：fetch 请求会在 generateMetadata、generateStaticParams、布局、页面和服务器组件之间自动记忆化。如果 fetch 不可用，可以使用 React 的 cache。

版本历史

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

On this page