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 [{ id: '1' }, { id: '2' }, { id: '3' }]
}

// 将使用 `generateStaticParams` 返回的 `params` 静态生成此页面的三个版本
// - /product/1
// - /product/2
// - /product/3
export default function Page({ params }) {
  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 [
    { 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 }) {
  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
  // ...
}

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 }) {
  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] 和 [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: { 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: { 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 }) {
  // ...
}

须知：在所有以 generate 为前缀的函数、布局、页面和服务器组件中，fetch 请求会自动记忆化。如果 fetch 不可用，可以使用 React 的 cache。

仅生成部分参数

您可以通过返回仅包含要生成的动态段的对象数组来为路由生成部分参数。然后，通过使用 dynamicParams 段配置选项，您可以控制当访问未通过 generateStaticParams 生成的动态段时会发生什么。

app/blog/[slug]/page.js

// 除了前 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,
  }))
}

版本历史

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

On this page