夜雨聆风目录
一、本章要学什么 二、先建立最基本的认知 三、动态路由基础 四、catch-all 路由 五、可选 catch-all 路由 六、路由分组 七、useParams Hook 八、useSelectedLayoutSegment 与 useSelectedLayoutSegments 九、Link 预取机制 十、useLinkStatus Hook 十一、嵌套路由与动态路由的组合 十二、常见路由配置组合 十三、常见误区 十四、与其他章节的关联 十五、至少要能回答的问题 十六、知识点清单 十七、收尾建议
本章聚焦 Next.js 16 App Router 的路由系统核心知识，是前两章文件约定基础上的延伸。完成本章学习后，你将掌握：
- 动态路由
- 如何用方括号语法处理可变路径段 - 可选 catch-all 与 catch-all
- 处理多层级未知深度的路由 - 路由分组
- 组织目录结构而不影响 URL - 路由参数 hooks
- useParams、useSelectedLayoutSegment、useSelectedLayoutSegments - Link 预取与状态
- useLinkStatus、prefetch 行为
这些是构建复杂应用路由结构的必备知识。
二、先建立最基本的认知
前两章我们学习了 App Router 的文件约定，知道page.tsx决定路由入口。
本章则聚焦如何用方括号语法和路由分组构建灵活多变的路由结构。
核心记忆点：
[param]匹配单个路径段 [...param]捕获剩余全部路径 [[...param]]可选的 catch-all (group)只做组织，不影响 URL
三、动态路由基础
1. 什么是动态路由
静态路由对应固定路径，例如/blog始终指向同一个页面。
动态路由则允许路径中包含变量，例如/blog/nextjs和/blog/react都对应同一个页面文件，只是 slug 值不同。
2. 基本语法
用方括号[]包裹目录名，即可创建动态路由段：
app/├── blog/│ └── [slug]/│ └── page.tsx这个结构会匹配：
/blog/nextjs/blog/react/blog/any-value
3. page.tsx 中获取参数
动态路由段的参数会传入 page 的params属性：
// app/blog/[slug]/page.tsxexport default async function Page({ params,}:{ params:Promise<{ slug:string}>}){ const { slug } = await params return<h1>文章详情: {slug}</h1>}4. 多个动态段
可以同时使用多个动态段：
app/├── blog/│ └── [category]/│ └── [slug]/│ └── page.tsxURL/blog/javascript/nextjs会匹配这个结构，其中：
category= javascript slug= nextjs
// app/blog/[category]/[slug]/page.tsxexport default async function Page({ params,}:{ params:Promise<{ category:string; slug:string}>}){const{ category, slug }=await paramsreturn( <h1> {category} 类目下的文章: {slug} </h1>)}5. params 是 Promise
在 Next.js 16 中，params和searchParams都是 Promise 形式，需要await：
export default async function Page({ params, searchParams,}:{ params:Promise<{ slug:string}> searchParams:Promise<{[key:string]:string|string[]|undefined}>}){const { slug } = await paramsconst query = await searchParams// ...}四、catch-all 路由
1. 基本概念
有时候路径层级不确定，例如文档路由：
/docs/getting-started/docs/getting-started/installation/docs/getting-started/installation/windows
这种情况下需要用catch-all语法[...slug]。
2. 语法与匹配
app/└── docs/ └── [...slug]/ └── page.tsx[...slug]会捕获从该位置开始的所有路径段：
/docs | |
/docs/getting-started | ['getting-started'] |
/docs/getting-started/installation | ['getting-started', 'installation'] |
3. 代码示例
// app/docs/[...slug]/page.tsxexport default async function Page({ params,}:{ params:Promise<{ slug:string[]}>}){const { slug } = await paramsreturn(<div> <h1>文档路径</h1> <p>路径段数量: {slug.length}</p> <ul> {slug.map((segment, index)=>( <li key={index}>{segment}</li> ))} </ul></div>)}4. catch-all vs 嵌套静态路由
两种方式都可以处理多层路由：
方式一：嵌套静态路由
app/├── docs/│ ├── page.tsx│ ├── getting-started/│ │ └── page.tsx│ └── guides/│ └── page.tsx方式二：catch-all
app/└── docs/ └── [...slug]/ └── page.tsx选择建议：
路由层级确定且不多时，用嵌套静态路由更清晰 层级不确定或可能很深时，用 catch-all 更灵活
五、可选 catch-all 路由
1. 基本概念
catch-all
[...slug]要求至少匹配一段，URL/docs不会匹配。如果希望空路径也能匹配，使用可选 catch-all
[[...slug]]。
2. 语法与匹配
app/└── docs/ └── [[...slug]]/ └── page.tsx/docs | [] |
/docs/getting-started | ['getting-started'] |
3. 代码示例
// app/docs/[[...slug]]/page.tsxexport default async function Page({ params,}:{ params:Promise<{ slug?:string[]}>}){const { slug } = await paramsif (!slug || slug.length===0){ return<h1>文档首页</h1>}return( <div> <h1>文档路径</h1> <p>当前路径: /docs/{slug.join('/')}</p> </div>)}4. 对比总结
/docs | /docs/a | /docs/a/b | |
|---|---|---|---|
[slug] | ['a'] | ['a', 'b'] | |
[...slug] | ['a'] | ['a', 'b'] | |
[[...slug]] | [] | ['a'] | ['a', 'b'] |
六、路由分组
1. 基本概念
路由分组使用圆括号(folder)语法，作用是组织目录结构而不影响 URL。
2. 语法
app/├── (marketing)/│ ├── about/│ │ └── page.tsx → /about│ └── contact/│ └── page.tsx → /contact└── (shop)/ ├── products/ │ └── page.tsx → /products └── cart/ └── page.tsx → /cart虽然目录结构有(marketing)和(shop)两层分组，但 URL 中不会出现这些括号包裹的文件夹名。
3. 使用场景
场景一：按业务线分组
app/├── (main)/│ ├── page.tsx → /│ ├── about/│ └── contact/└── (dashboard)/ ├── page.tsx → /dashboard ├── analytics/ └── settings/场景二：不同布局需要
app/├── (public)/│ ├── layout.tsx # 公开布局（无侧边栏）│ ├── page.tsx → /│ └── about/│ └── page.tsx → /about└── (private)/ ├── layout.tsx # 私密布局（有侧边栏） ├── dashboard/ │ └── page.tsx → /dashboard └── settings/ └── page.tsx → /settings4. 与 private folder 的区别
(folder) | _folder | |
|---|---|---|
5. 注意事项
同一路由段下不能有两个 page.tsx，即使在不同分组中也不行分组主要用于布局共享和目录组织
七、useParams Hook
1. 基本概念
useParams是客户端组件用于获取当前路由参数的 Hook。
2. 语法
'use client'import { useParams } from 'next/navigation'export default function PostNav(){ const params =useParams()// params = { slug: 'nextjs' } (单个动态段)// params = { category: 'js', slug: 'next' } (多个动态段) return( <nav> <p>当前文章: {params.slug}</p> </nav>)}3. 返回值类型
// 单个动态段// URL: /blog/nextjsuseParams()// → { slug: string }// 多个动态段// URL: /blog/js/nextjsuseParams()// → { category: string, slug: string }// catch-all// URL: /docs/getting-started/installationuseParams()// → { slug: string[] }4. 常见用法
'use client'import { useParams, useRouter } from 'next/navigation'export default function Breadcrumb(){ const params =useParams() const router =useRouter() const category = params.category const slug = params.slugreturn(<nav> <button onClick={()=> router.push(`/blog/${category}`)}> 返回 {category} 类目 </button> <span> / </span> <span>{slug}</span></nav>)}5. 注意事项
useParams只在客户端组件中可用 Server Components 直接从 page.tsx的params属性获取参数
八、useSelectedLayoutSegment 与 useSelectedLayoutSegments
1. useSelectedLayoutSegment
获取当前布局层级中最近的一个路由段。
'use client'import { useSelectedLayoutSegment } from 'next/navigation'export default function Sidebar(){ const segment = useSelectedLayoutSegment()// 假设 URL 是 /dashboard/analytics// 如果 Sidebar 在 dashboard 布局中// segment = 'analytics' return( <aside> <p>当前段落: {segment}</p> {/* 根据当前段渲染不同内容 */} </aside> )}2. useSelectedLayoutSegments
获取从根布局到当前布局的所有路由段数组。
'use client'import { useSelectedLayoutSegments } from 'next/navigation'export default function Breadcrumb(){const segments = useSelectedLayoutSegments()// URL: /dashboard/analytics/2024// segments = ['dashboard', 'analytics', '2024']return(<nav>{segments.map((segment, index)=>(<span key={index}> {index >0 && ' / '} {segment}</span>))}</nav>)}3. 对比
useSelectedLayoutSegment | /dashboard/analytics | 'analytics' | |
useSelectedLayoutSegments | /dashboard/analytics | ['dashboard', 'analytics'] |
4. 典型应用场景
侧边栏高亮当前菜单
'use client'import Link from 'next/link'import { useSelectedLayoutSegment } from 'next/navigation'const menuItems = [ { href:'/dashboard', label:'概览', segment:null}, { href:'/dashboard/analytics', label:'分析', segment:'analytics'}, { href:'/dashboard/settings', label:'设置', segment:'settings'},]export default function Sidebar(){const activeSegment = useSelectedLayoutSegment()return(<aside>{menuItems.map((item)=>(<Linkkey={item.href}href={item.href}style={{fontWeight: activeSegment === item.segment ? 'bold' : 'normal'}}> {item.label}</Link>))}</aside>)}九、Link 预取机制
1. 什么是预取
当 Link 组件进入视口时，Next.js 会预先加载目标页面的代码和数据，使得用户点击时能够瞬间切换。
2. 默认行为
import Link from 'next/link'// 默认预取：鼠标悬停或进入视口时预取export default function Nav(){return( <nav> <Link href="/dashboard">仪表盘</Link> <Link href="/blog">博客</Link> </nav>)}3. 禁用预取
某些页面数据量大或不需要预取时，可以禁用：
import Link from 'next/link'// 禁用预取<Link href="/dashboard" prefetch={false}> 仪表盘</Link>4. 预取层级
prefetch属性支持三种值：
<Link href="/dashboard" prefetch={true}> // 默认，预取完整数据<Link href="/dashboard" prefetch="minimal"> // 只预取 JS bundle，不预取数据<Link href="/dashboard" prefetch={false}> // 完全禁用预取5. 预取与缓存交互
预取只加载代码和静态数据，不会触发 Server Components 的完整数据获取。
真正的数据获取发生在页面渲染时。
十、useLinkStatus Hook
1. 基本概念
useLinkStatus用于获取 Link 组件的加载状态，常用于显示导航进度。
2. 语法
'use client'import { useLinkStatus } from 'next/navigation'export default function NavigationStatus(){ const { isPending, href } = useLinkStatus() if (isPending){ return<p>正在加载: {href}</p> } return null}3. 返回值
{ isPending:boolean// 是否正在加载目标页面 href:string// 正在加载的目标 href}4. 典型应用
全局加载指示器
// app/components/NavigationStatus.tsx'use client'import { useLinkStatus } from 'next/navigation'export default function NavigationStatus(){const { isPending } = useLinkStatus() if(!isPending)return nullreturn(<div style={{ position:'fixed', top:0, left:0, right:0, height:'2px', background:'blue', animation:'loading 1s infinite'}}/>)}按钮加载状态
'use client'import Link from 'next/link'import { useLinkStatus } from 'next/navigation'export function NavButton({ href, children }:{ href:string; children:React.ReactNode}){const { isPending, href: pendingHref } = useLinkStatus()const isThisLinkPending = isPending && pendingHref === hrefreturn(<Link href={href}> {children} {isThisLinkPending && <span>加载中...</span> }</Link>)}十一、嵌套路由与动态路由的组合
1. 复杂路由结构示例
app/├── (main)/│ └── blog/│ ├── page.tsx → /blog│ ├── loading.tsx → /blog 加载态│ ├── [category]/│ │ ├── page.tsx → /blog/:category│ │ └── [slug]/│ │ ├── page.tsx → /blog/:category/:slug│ │ └── loading.tsx → /blog/:category/:slug 加载态│ └── [[...slug]]/│ └── page.tsx → /blog/* (catch-all)2. 布局嵌套关系
root layout (app/layout.tsx) └── (main) layout (app/(main)/layout.tsx) └── blog layout (app/(main)/blog/layout.tsx) └── [category] layout (app/(main)/blog/[category]/layout.tsx) └── [slug] page (app/(main)/blog/[category]/[slug]/page.tsx)3. 数据流与参数传递
在多层嵌套中，布局和页面都能访问到 params：
// app/(main)/blog/[category]/[slug]/page.tsxexport default async function Page({ params,}:{ params:Promise<{ category:string; slug:string}>}){const { category, slug } = await params// 从数据库获取文章const post = await getPost(category, slug)return(<article> <p>类目: {category}</p> <h1>{post.title}</h1> <p>{post.content}</p></article>)}十二、常见路由配置组合
1. 博客系统
app/├── blog/│ ├── page.tsx → /blog (列表页)│ ├── [slug]/│ │ └── page.tsx → /blog/:slug (详情页)│ └── category/│ └── [category]/│ └── page.tsx → /blog/category/:category (分类页)2. 管理系统
app/├── (dashboard)/│ ├── layout.tsx # 仪表盘专用布局│ ├── page.tsx → /dashboard│ ├── users/│ │ └── page.tsx → /dashboard/users│ └── settings/│ ├── page.tsx → /dashboard/settings│ └── [[...section]]/│ └── page.tsx → /dashboard/settings/* (设置详情)3. 文档系统
app/├── docs/│ ├── page.tsx → /docs│ └── [[...slug]]/│ └── page.tsx → /docs/*十三、常见误区
误区 1：动态路由参数不用 await
在 Next.js 16 中，params和searchParams都是 Promise，必须 await：
// ❌ 错误export default function Page({ params }:{ params:{ slug:string}}){ return<h1>{params.slug}</h1>}// ✅ 正确export default async function Page({ params }:{ params:Promise<{ slug:string}>}){ const { slug } = await params return<h1>{slug}</h1>}误区 2：路由分组会影响 URL
路由分组(group)只是组织目录用，URL 中不会出现：
app/(marketing)/about/page.tsx → /about (不是 /(marketing)/about)误区 3：catch-all 可以匹配任意深度
[...slug]确实可以匹配任意深度，但必须至少有一段：
[...slug] → /a ✓ /a/b/c ✓ / ✗[[...slug]] → /a ✓ /a/b/c ✓ / ✓误区 4：useParams 在 Server Components 中使用
useParams是客户端 Hook，只能在标记'use client'的组件中使用。
Server Components 直接从page.tsx的 props 中获取 params。
十四、与其他章节的关联
本章学习的路由系统是后续章节的基础：
- Day 4 (Server/Client Components)
: 路由参数如何在服务端和客户端组件中使用 - Day 5 (数据获取)
: generateStaticParams 与动态路由的静态生成 - Day 6 (平行/拦截路由)
: 在平行路由中使用 useSelectedLayoutSegment - Day 7 (导航控制)
: useRouter、usePathname、useSearchParams
十五、至少要能回答的问题
学完本章后，应能回答以下问题：
[slug]、[...slug]、[[...slug]]三种语法的区别是什么？
路由分组 (group)对 URL 有什么影响？如何在 page.tsx 中获取动态路由参数？ useParams和 page 的 paramsprops 有什么区别？useSelectedLayoutSegment和 useSelectedLayoutSegments返回值有什么不同？Link 组件的预取机制是什么？如何禁用预取？ useLinkStatus返回哪些信息？典型使用场景是什么？
十六、知识点清单
路由语法
动态路由 [slug]catch-all [...slug]可选 catch-all [[...slug]]路由分组 (folder)
Hooks
useParams useSelectedLayoutSegment useSelectedLayoutSegments useLinkStatus
Link 相关
prefetch prefetch="minimal" prefetch={false}
概念
params 是 Promise 嵌套路由 路由匹配优先级 预取机制
十七、收尾建议
本章的核心目标是掌握 Next.js 16 的路由系统核心语法与 Hooks：
- 动手实践
：创建包含动态路由的博客结构，验证参数获取 - 对比记忆
：三种 catch-all 语法的匹配差异 - 理解场景
：什么情况下用路由分组，用不用有什么区别
下一章我们将学习 Server Components 与 Client Components，理解这些路由参数如何在两种组件类型间流转。
