动态路由段

当你事先不知道确切的路由段名称，并希望从动态数据创建路由时，可以使用在请求时填充或在构建时预渲染的动态段。

约定

可以通过将文件夹名称包装在方括号中来创建动态段：[folderName]。例如，博客可以包含以下路由 app/blog/[slug]/page.js，其中 [slug] 是博客文章的动态段。

TypeScript

app/blog/[slug]/page.tsx

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <div>My Post: {slug}</div>
}

JavaScript

app/blog/[slug]/page.js

export default async function Page({ params }) {
  const { slug } = await params
  return <div>My Post: {slug}</div>
}

动态段作为 params prop 传递给 layout、page、route 和 generateMetadata 函数。

路由	示例 URL	params
app/blog/[slug]/page.js	/blog/a	{ slug: 'a' }
app/blog/[slug]/page.js	/blog/b	{ slug: 'b' }
app/blog/[slug]/page.js	/blog/c	{ slug: 'c' }

在客户端组件中

在客户端组件页面中，可以使用 use 钩子从 props 访问动态段。

TypeScript

app/blog/[slug]/page.tsx

'use client'
import { use } from 'react'

export default function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = use(params)

  return (
    <div>
      <p>{slug}</p>
    </div>
  )
}

JavaScript

app/blog/[slug]/page.js

'use client'
import { use } from 'react'
import { useParams } from 'next/navigation'

export default function BlogPostPage({ params }) {
  const { slug } = use(params)

  return (
    <div>
      <p>{slug}</p>
    </div>
  )
}

或者，客户端组件可以使用 useParams 钩子在客户端组件树的任何位置访问 params。

捕获所有段

动态段可以通过在方括号内添加省略号 [...folderName] 来扩展为捕获所有后续段。

例如，app/shop/[...slug]/page.js 将匹配 /shop/clothes，但也匹配 /shop/clothes/tops、/shop/clothes/tops/t-shirts 等。

路由	示例 URL	params
app/shop/[...slug]/page.js	/shop/a	{ slug: ['a'] }
app/shop/[...slug]/page.js	/shop/a/b	{ slug: ['a', 'b'] }
app/shop/[...slug]/page.js	/shop/a/b/c	{ slug: ['a', 'b', 'c'] }

可选捕获所有段

捕获所有段可以通过在双方括号中包含参数来使其可选：[[...folderName]]。

例如，app/shop/[[...slug]]/page.js 将也匹配 /shop，除了 /shop/clothes、/shop/clothes/tops、/shop/clothes/tops/t-shirts。

捕获所有和可选捕获所有段之间的区别在于，使用可选时，没有参数的路由也会被匹配（上例中的 /shop）。

路由	示例 URL	params
app/shop/[[...slug]]/page.js	/shop	{ slug: undefined }
app/shop/[[...slug]]/page.js	/shop/a	{ slug: ['a'] }
app/shop/[[...slug]]/page.js	/shop/a/b	{ slug: ['a', 'b'] }
app/shop/[[...slug]]/page.js	/shop/a/b/c	{ slug: ['a', 'b', 'c'] }

TypeScript

使用 TypeScript 时，你可以根据配置的路由段为 params 添加类型。

路由	params 类型定义
app/blog/[slug]/page.js	{ slug: string }
app/shop/[...slug]/page.js	{ slug: string[] }
app/shop/[[...slug]]/page.js	{ slug?: string[] }
app/[categoryId]/[itemId]/page.js	{ categoryId: string, itemId: string }

行为

• 由于 params prop 是一个 Promise，你必须使用 async/await 或 React 的 use 函数来访问值。
  • 在版本 14 及更早版本中，params 是一个同步 prop。为了帮助向后兼容，你在 Next.js 15 中仍然可以同步访问它，但此行为将在未来被弃用。

示例

使用 generateStaticParams

generateStaticParams 函数可用于在构建时静态生成路由，而不是在请求时按需生成。

TypeScript

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

JavaScript

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

在 generateStaticParams 函数中使用 fetch 时，请求会自动去重。这避免了为相同数据的布局、页面和其他 generateStaticParams 函数进行多次网络调用，从而加快构建时间。