NNext.js 中文网 GitHub

动态路由片段

使用动态片段读取 URL 路径参数并根据动态数据生成路由。

URL 路径是一系列路径片段。在 App Router 中,片段可以是静态的(精确匹配的字面值)或动态的(从 URL 中捕获值的占位符)。当你事先不知道某个片段的值时,可以定义动态片段来根据动态数据创建路由。Next.js 通过路径 params prop 将捕获的值传递给你的页面,这些值要么在请求时填充,要么在构建时预渲染。

小知识:动态片段通常也被称为路径参数、路由参数或 URL 参数。

约定#

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

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>
}
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 函数。

路由示例 URLparams
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' }

出现在root 布局之前的动态片段是根参数,还可以使用 next/root-params从任意 Server Component 中读取。

在 Client Component 中#

在 Client Component 页面中,可以使用 use API 访问来自 props 的动态片段。

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>
  )
}
app/blog/[slug]/page.js
'use client'
import { use } from 'react'

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

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

此外,Client Component 可以使用 useParams Hook 在 Client Component 树中的任意位置访问 params。

捕获所有片段(Catch-all Segments)#

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

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

路由示例 URLparams
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]]。

例如,除了 /shop/clothes、/shop/clothes/tops、/shop/clothes/tops/t-shirts 之外,app/shop/[[...slug]]/page.js 还会匹配 /shop。

捕获所有片段与可选捕获所有片段的区别在于,可选情况下不带参数的路由也会被匹配(上例中的 /shop)。

路由示例 URLparams
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 添加类型——分别使用 PageProps<'/route'>、LayoutProps<'/route'> 或 RouteContext<'/route'> 为 page、layout 和 route 中的 params 指定类型。

路由 params 值的类型为 string、string[] 或 undefined(对于可选的捕获所有片段),因为其值直到运行时才知道。用户可以在地址栏输入任意 URL,这些宽泛的类型有助于确保应用代码处理所有可能的情况。

路由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 只能有固定数量有效值的路由,例如具有已知语言代码集合的 [locale] 参数,可以使用运行时验证来处理用户可能输入的任何无效参数,并让应用其余部分使用来自已知集合的更窄类型。

/app/[locale]/page.tsx
import { notFound } from 'next/navigation'
import type { Locale } from '@i18n/types'
import { isValidLocale } from '@i18n/utils'

function assertValidLocale(value: string): asserts value is Locale {
  if (!isValidLocale(value)) notFound()
}

export default async function Page(props: PageProps<'/[locale]'>) {
  const { locale } = await props.params // locale 的类型为 string
  assertValidLocale(locale)
  // 现在 locale 的类型为 Locale
}

行为#

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

使用 Cache Components#

将 Cache Components与动态路由片段一起使用时,处理 params 的方式取决于你是否使用 generateStaticParams。

不使用 generateStaticParams 时,参数值在预渲染期间未知,因此 params 属于运行时数据。必须将参数访问包裹在 <Suspense> 边界中,以提供 fallback UI。

使用 generateStaticParams 时,你提供可在构建时使用的示例参数值。构建过程会验证动态内容和其他运行时 API 是否得到正确处理,然后为这些示例生成静态 HTML 文件。使用运行时参数渲染的页面会在首次请求成功后保存到磁盘。

以下各节演示了这两种模式。

不使用 generateStaticParams#

所有参数都是运行时数据。参数访问必须由 Suspense fallback UI 包裹。Next.js 在构建时生成静态外壳,内容在每次请求时加载。

小知识:

  • 还可以使用 loading.tsx作为页面级 fallback UI。
  • 在布局中,避免在顶层 await params。这样做会阻止布局被预渲染。请将 params promise 传递给需要它的组件,并在那里 await。示例请参阅最大化静态外壳。
app/blog/[slug]/page.tsx
import { Suspense } from 'react'

export default function Page({ params }: PageProps<'/blog/[slug]'>) {
  return (
    <div>
      <h1>Blog Post</h1>
      <Suspense fallback={<div>Loading...</div>}>
        {params.then(({ slug }) => (
          <Content slug={slug} />
        ))}
      </Suspense>
    </div>
  )
}

async function Content({ slug }: { slug: string }) {
  const res = await fetch(`https://api.vercel.app/blog/${slug}`)
  const post = await res.json()

  return (
    <article>
      <h2>{post.title}</h2>
      <p>{post.content}</p>
    </article>
  )
}

使用 generateStaticParams#

提前提供参数,以便在构建时预渲染页面。你可以根据需要预渲染所有路由或一个子集。

在构建过程中,会使用每个示例参数执行路由以收集 HTML 结果。如果动态内容或运行时数据被错误地访问,构建将失败。

app/blog/[slug]/page.tsx
import { Suspense } from 'react'

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

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params

  return (
    <div>
      <h1>Blog Post</h1>
      <Content slug={slug} />
    </div>
  )
}

async function Content({ slug }: { slug: string }) {
  const post = await getPost(slug)
  return (
    <article>
      <h2>{post.title}</h2>
      <p>{post.content}</p>
    </article>
  )
}

async function getPost(slug: string) {
  'use cache'
  const res = await fetch(`https://api.vercel.app/blog/${slug}`)
  return res.json()
}

构建时验证仅覆盖使用示例参数执行的代码路径。如果你的路由包含针对示例中未包含的某些参数值访问运行时 API 的条件逻辑,这些分支在构建时不会得到验证:

app/blog/[slug]/page.tsx
import { cookies } from 'next/headers'

export async function generateStaticParams() {
  return [{ slug: 'public-post' }, { slug: 'hello-world' }]
}

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params

  if (slug.startsWith('private-')) {
    // 该分支在构建时永远不会执行
    // 对 'private-*' slug 的运行时请求将报错
    return <PrivatePost slug={slug} />
  }

  return <PublicPost slug={slug} />
}

async function PrivatePost({ slug }: { slug: string }) {
  const token = (await cookies()).get('token')
  // ... 使用 token 进行身份验证,获取并渲染私有文章
}

对于 generateStaticParams 未返回的运行时参数,验证会在首次请求期间进行。在上例中,以 private- 开头的 slug 请求会失败,因为 PrivatePost 在没有 Suspense 边界的情况下访问了 cookies()。其他未进入条件分支的运行时参数会成功渲染,并保存到磁盘供后续请求使用。

要解决此问题,请用 Suspense 包裹 PrivatePost:

app/blog/[slug]/page.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'

export async function generateStaticParams() {
  return [{ slug: 'public-post' }, { slug: 'hello-world' }]
}

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params

  if (slug.startsWith('private-')) {
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <PrivatePost slug={slug} />
      </Suspense>
    )
  }

  return <PublicPost slug={slug} />
}

async function PrivatePost({ slug }: { slug: string }) {
  const token = (await cookies()).get('token')
  // ... 使用 token 进行身份验证,获取并渲染私有文章
}

示例#

使用 generateStaticParams#

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

在 generateStaticParams 函数内部使用 fetch 时,请求会自动去重。这避免了 Layout、Page 和其他 generateStaticParams 函数对相同数据进行多次网络调用,从而加快构建速度。

使用 generateStaticParams 的动态 GET Route Handler#

generateStaticParams 也适用于动态 Route Handler,可在构建时静态生成 API 响应:

app/api/posts/[id]/route.ts
export async function generateStaticParams() {
  const posts: { id: number }[] = await fetch(
    'https://api.vercel.app/blog'
  ).then((res) => res.json())

  return posts.map((post) => ({
    id: `${post.id}`,
  }))
}

export async function GET(
  request: Request,
  { params }: RouteContext<'/api/posts/[id]'>
) {
  const { id } = await params
  const res = await fetch(`https://api.vercel.app/blog/${id}`)

  if (!res.ok) {
    return Response.json({ error: 'Post not found' }, { status: 404 })
  }

  const post = await res.json()
  return Response.json(post)
}
app/api/posts/[id]/route.js
export async function generateStaticParams() {
  const posts = await fetch('https://api.vercel.app/blog').then((res) =>
    res.json()
  )

  return posts.map((post) => ({
    id: `${post.id}`,
  }))
}

export async function GET(request, { params }) {
  const { id } = await params
  const res = await fetch(`https://api.vercel.app/blog/${id}`)

  if (!res.ok) {
    return Response.json({ error: 'Post not found' }, { status: 404 })
  }

  const post = await res.json()
  return Response.json(post)
}

在此示例中,generateStaticParams 返回的所有博客文章 ID 对应的 Route Handler 都会在构建时静态生成。对其他 ID 的请求将在请求时动态处理。

Next.js 中文网