目录

• 一、本章要学什么
• 二、先建立最基本的认知
• 三、动态路由基础
• 四、catch-all 路由
• 五、可选 catch-all 路由
• 六、路由分组
• 七、useParams Hook
• 八、useSelectedLayoutSegment 与 useSelectedLayoutSegments
• 九、Link 预取机制
• 十、useLinkStatus Hook
• 十一、嵌套路由与动态路由的组合
• 十二、常见路由配置组合
• 十三、常见误区
• 十四、与其他章节的关联
• 十五、至少要能回答的问题
• 十六、知识点清单
• 十七、收尾建议

本章聚焦 Next.js 16 App Router 的路由系统核心知识，是前两章文件约定基础上的延伸。完成本章学习后，你将掌握：

1. 动态路由
   - 如何用方括号语法处理可变路径段
2. 可选 catch-all 与 catch-all
   - 处理多层级未知深度的路由
3. 路由分组
   - 组织目录结构而不影响 URL
4. 路由参数 hooks
   - useParams、useSelectedLayoutSegment、useSelectedLayoutSegments
5. 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.tsx

URL/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]会捕获从该位置开始的所有路径段：

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

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. 对比总结

六、路由分组

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      → /settings

4. 与 private 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. 对比

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

十五、至少要能回答的问题

学完本章后，应能回答以下问题：

1. [slug]、[...slug]、[[...slug]]三种语法的区别是什么？

2. 路由分组(group)对 URL 有什么影响？
3. 如何在 page.tsx 中获取动态路由参数？
4. useParams
   和 page 的paramsprops 有什么区别？
5. useSelectedLayoutSegment
   和useSelectedLayoutSegments返回值有什么不同？
6. Link 组件的预取机制是什么？如何禁用预取？
7. 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：

1. 动手实践
   ：创建包含动态路由的博客结构，验证参数获取
2. 对比记忆
   ：三种 catch-all 语法的匹配差异
3. 理解场景
   ：什么情况下用路由分组，用不用有什么区别

下一章我们将学习 Server Components 与 Client Components，理解这些路由参数如何在两种组件类型间流转。