Next.js 中的 generateStaticParams 函数详解

什么是 generateStaticParams

generateStaticParams 是 Next.js 应用路由（App Router）中的一个关键函数，用于在构建时静态生成动态路由。它取代了之前页面路由（Pages Router）中的 getStaticPaths 函数，提供了更简洁的 API 和更好的开发体验。

核心功能

这个函数的主要作用是：

1. 定义哪些动态路由应该在构建时预先生成
2. 为每个动态路由提供具体的参数值
3. 配合动态路由段实现静态站点生成（SSG）

基本用法

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

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

在这个例子中，generateStaticParams 获取文章列表，并为每篇文章返回一个包含 slug 参数的对象。Next.js 会根据这些参数在构建时生成对应的静态页面。

不同场景下的应用

1. 单一动态段

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

这会生成三个静态页面：/product/1、/product/2 和 /product/3。

2. 多个动态段

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

这会生成三个静态页面：/products/a/1、/products/b/2 和 /products/c/3。

3. 捕获所有动态段

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

这会生成三个静态页面：/product/a/1、/product/b/2 和 /product/c/3。

高级用法

构建时生成所有路径

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.slice(0, 10).map((post) => ({ slug: post.slug }))
}

运行时生成路径

export async function generateStaticParams() {
  return [] // 返回空数组表示所有路径将在运行时生成
}

或者使用：

export const dynamic = 'force-static'

多级动态路由处理

对于嵌套的动态路由，如 app/products/[category]/[product]，有两种处理方式：

1. 自底向上：在子路由中生成所有参数
2. 自顶向下：在父路由中生成部分参数，子路由使用父路由的参数生成自己的参数

自底向上示例

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 async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())
  return products.map((product) => ({
    category: product.category.slug,
  }))
}

子路由：

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,
  }))
}

最佳实践

1. 数据获取优化：Next.js 会自动对相同数据的 fetch 请求进行记忆化处理
2. 缓存控制：可以使用 React 的 cache 函数来优化非 fetch 的数据获取
3. 错误处理：确保 generateStaticParams 中的异步操作有适当的错误处理
4. 性能考虑：对于大型数据集，考虑分批次生成或使用增量静态再生（ISR）

版本历史

• v13.0.0：首次引入 generateStaticParams 函数

通过合理使用 generateStaticParams，开发者可以灵活控制 Next.js 应用的静态生成策略，在构建性能和运行时灵活性之间取得平衡。