动态路由片段
使用动态片段读取 URL 路径参数并根据动态数据生成路由。
URL 路径是一系列路径片段。在 App Router 中,片段可以是静态的(精确匹配的字面值)或动态的(从 URL 中捕获值的占位符)。当你事先不知道某个片段的值时,可以定义动态片段来根据动态数据创建路由。Next.js 通过路径 params prop 将捕获的值传递给你的页面,这些值要么在请求时填充,要么在构建时预渲染。
小知识:动态片段通常也被称为路径参数、路由参数或 URL 参数。
约定#
可以通过用方括号包裹文件夹名称来创建动态片段:[folderName]。例如,博客可以包含以下路由 app/blog/[slug]/page.js,其中 [slug] 是博客文章的动态片段。
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return <div>My Post: {slug}</div>
}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' } |
出现在root 布局之前的动态片段是根参数,还可以使用 next/root-params从任意 Server Component 中读取。
在 Client Component 中#
在 Client Component 页面中,可以使用 use API 访问来自 props 的动态片段。
'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>
)
}'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 等。
| 路由 | 示例 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]]。
例如,除了 /shop/clothes、/shop/clothes/tops、/shop/clothes/tops/t-shirts 之外,app/shop/[[...slug]]/page.js 还会匹配 /shop。
捕获所有片段与可选捕获所有片段的区别在于,可选情况下不带参数的路由也会被匹配(上例中的 /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 添加类型——分别使用 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] 参数,可以使用运行时验证来处理用户可能输入的任何无效参数,并让应用其余部分使用来自已知集合的更窄类型。
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
}行为#
- 由于
paramsprop 是一个 promise,必须使用async/await或 React 的 use 函数来访问其值。- 在 14 及更早版本中,
params是一个同步 prop。为了向后兼容,在 Next.js 15 中你仍可以同步访问它,但此行为将来会被弃用。
- 在 14 及更早版本中,
使用 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。示例请参阅最大化静态外壳。
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 结果。如果动态内容或运行时数据被错误地访问,构建将失败。
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 的条件逻辑,这些分支在构建时不会得到验证:
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:
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 函数可用于在构建时静态生成路由,而不是在请求时按需生成。
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.map((post) => ({
slug: post.slug,
}))
}在 generateStaticParams 函数内部使用 fetch 时,请求会自动去重。这避免了 Layout、Page 和其他 generateStaticParams 函数对相同数据进行多次网络调用,从而加快构建速度。
使用 generateStaticParams 的动态 GET Route Handler#
generateStaticParams 也适用于动态 Route Handler,可在构建时静态生成 API 响应:
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)
}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 的请求将在请求时动态处理。