NNext.js 中文网 GitHub

generateStaticParams

generateStaticParams 函数的 API 参考。

generateStaticParams 函数可与动态路由段结合使用,以便在构建时静态生成路由,而不是在请求时按需生成。

generateStaticParams 可用于:

app/blog/[slug]/page.tsx
// 返回一个 `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
  // ...
}
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 async function Page({ params }) {
  const { slug } = await params
  // ...
}

小知识:

参数#

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[] }[]

单个动态段#

app/product/[id]/page.tsx
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
  // ...
}
app/product/[id]/page.js
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
  // ...
}

多个动态段#

app/products/[category]/[product]/page.tsx
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
  // ...
}
app/products/[category]/[product]/page.js
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
  // ...
}

捕获所有动态段#

app/product/[...slug]/page.tsx
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
  // ...
}
app/product/[...slug]/page.js
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 提供完整的路径列表:

app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}
app/blog/[slug]/page.js
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

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

构建时生成部分路径#

要在构建时静态渲染一部分路径,其余路径在运行时首次访问时渲染,请返回部分路径列表:

app/blog/[slug]/page.tsx
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,
  }))
}
app/blog/[slug]/page.js
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 生成的动态段时会发生什么。

app/blog/[slug]/page.tsx
// 除前 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,
  }))
}
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,
  }))
}

运行时生成所有路径#

要在首次访问时静态渲染所有路径,请返回一个空数组(构建时不会渲染任何路径)或使用 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'

使用 Cache Components#

当对动态路由使用 Cache Components 时,generateStaticParams 必须返回至少一个参数。空数组会导致构建错误。这让 Cache Components 能够验证你的路由不会在运行时错误地访问 cookies()、headers() 或 searchParams。

小知识:如果你在构建时不知道实际的参数值,可以返回一个占位参数(例如 [{ slug: '__placeholder__' }])用于验证,然后在页面中用 notFound() 处理它。但是,这会导致构建时验证无法有效工作,并可能引发运行时错误。

有关详细演练,请参阅动态路由部分,或参阅使用 Cache Components 的 ISR 以预渲染一部分路由并为其余路由提供 App Shell。

与 Route Handler 一起使用#

你可以将 generateStaticParams 与 Route Handler 一起使用,以便在构建时静态生成 API 响应:

app/api/posts/[id]/route.ts
export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

export async function GET(
  request: Request,
  { params }: RouteContext<'/api/posts/[id]'>
) {
  const { id } = await params
  // 这将针对 ID 1、2 和 3 进行静态生成
  return Response.json({ id, title: `Post ${id}` })
}
app/api/posts/[id]/route.js
export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

export async function GET(request, { params }) {
  const { id } = await params
  // 这将针对 ID 1、2 和 3 进行静态生成
  return Response.json({ id, title: `Post ${id}` })
}

使用 Cache Components 的 Route Handler#

使用 Cache Components 时,与 use cache 结合使用可获得最佳缓存效果:

app/api/posts/[id]/route.ts
export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

async function getPost(id: Promise<string>) {
  'use cache'
  const resolvedId = await id
  const response = await fetch(`https://api.example.com/posts/${resolvedId}`)
  return response.json()
}

export async function GET(
  request: Request,
  { params }: RouteContext<'/api/posts/[id]'>
) {
  const post = await getPost(params.then((p) => p.id))
  return Response.json(post)
}

有关更多详情,请参阅 Route Handler 文档。

禁止渲染未指定的路径#

要阻止未指定的路径在运行时被预渲染,请在路由段中添加 export const dynamicParams = false 选项。使用此配置选项时,只有 generateStaticParams 提供的路径会被提供,未指定的路由将返回 404 或匹配(在捕获所有路由的情况下)。

一个路由中的多个动态段#

你可以为当前布局或页面之上的动态段生成参数,但不能为它们之下的动态段生成参数。例如,给定 app/products/[category]/[product] 路由:

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

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

自下而上生成参数#

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

app/products/[category]/[product]/page.tsx
// 为 [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 }>
}) {
  // ...
}
app/products/[category]/[product]/page.js
// 为 [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 }) {
  // ...
}

自上而下生成参数#

先生成父段,再用结果生成子段。

app/products/[category]/layout.tsx
// 为 [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 }>
}) {
  // ...
}
app/products/[category]/layout.js
// 为 [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 来动态生成自己的段。

app/products/[category]/[product]/page.tsx
// 使用从父段的 `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 }>
}) {
  // ...
}
app/products/[category]/[product]/page.js
// 使用从父段的 `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 }) {
  // ...
}

请注意,params 参数可以同步访问,并且只包含父段的 params。

小知识: 当父动态段是根参数时,你还可以通过在嵌套的 generateStaticParams 中调用 next/root-params 模块的 getter 来读取它。

为了获得类型补全,你可以结合使用 TypeScript 的 Awaited 辅助类型与 Page Props helper 或 Layout Props helper:

app/products/[category]/[product]/page.tsx
export async function generateStaticParams({
  params: { category },
}: {
  params: Awaited<LayoutProps<'/products/[category]'>['params']>
}) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())

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

小知识:对于相同的数据,所有带 generate 前缀的函数、Layout、Page 和 Server Component 中的 fetch 请求都会自动记忆化。如果无法使用 fetch,可以使用 React 的 cache。

版本历史#

版本变更
v13.0.0引入 generateStaticParams。
Next.js 中文网