Next.js - 03 - 路由详解

Next.js 路由跳转

三者对比

1. 声明式跳转（最常用）

用<Link>组件，适合菜单、按钮、列表项等可点击链接。

基本用法

import Link from "next/link"; <Link href="/about">关于我们</Link>;

带动态路由参数

对应文件app/posts/[slug]/page.tsx（App Router 动态段直接写进路径字符串）：

const slug = 'hello-world' <Link href={`/posts/${slug}`}>文章详情</Link> <Link href={`/tags/${tagName}`}>标签页</Link>

带查询参数（Query String）

// 字符串写法（最直观） <Link href="/search?q=nextjs&page=2">搜索 Next.js</Link> // URLSearchParams（参数多、需编码时更安全） const params = new URLSearchParams({ q: 'nextjs', page: '2' }) <Link href={`/search?${params.toString()}`}>搜索 Next.js</Link> // 对象写法（仅固定 pathname + query，不含 [slug] 动态段） <Link href={{ pathname: '/search', query: { q: 'nextjs', page: '2' } }}> 搜索 Next.js </Link>

特点

• 客户端路由，不整页刷新
• 会预取（prefetch）目标页面，体验更好
• SEO 友好（本质是<a>）

2. 编程式跳转（代码里跳转）

在事件处理、登录成功后、表单提交后等场景使用。

基本用法

"use client"; import { useRouter } from "next/navigation"; const router = useRouter(); router.push("/dashboard"); // 跳转，可回退 router.replace("/login"); // 替换当前历史记录，不能回退到上一页 router.back(); // 返回 router.forward(); // 前进 router.refresh(); // 仅 App Router，URL 不变、不整页刷新，但让当前路由的 Server Component 重新跑一遍，拿到最新服务端数据。

和 push / 浏览器刷新的区别

典型场景

'use client' async function handleSubmit() { await updateProfile(formData) // 后端数据已更新 router.refresh() // 当前页重新拉服务端数据，UI 更新 // 不需要 router.push('/profile')，因为本来就在 profile 页 }

带动态路由参数

App Router 的router.push只接受字符串：

const slug = "hello-world"; router.push(`/posts/${slug}`); router.replace(`/tags/${tagName}`);

带查询参数

// 字符串写法 router.push("/search?q=nextjs&page=2"); // URLSearchParams const params = new URLSearchParams({ q: "nextjs", page: "2", sort: "date" }); router.push(`/search?${params.toString()}`); // 在当前页追加/修改 query（保留其他参数，需配合 usePathname / useSearchParams） import { usePathname, useSearchParams } from "next/navigation"; const pathname = usePathname(); const searchParams = useSearchParams(); const next = new URLSearchParams(searchParams.toString()); next.set("page", "3"); router.push(`${pathname}?${next.toString()}`);

常见方法

3. 服务端跳转（不经过客户端 JS）

适合权限校验、旧 URL 重定向、国际化路由等。

基本用法

import { redirect } from "next/navigation"; // Server Component / Server Action 中 redirect("/login");

带参数跳转

// 动态路由 redirect(`/posts/${slug}`); // 查询参数 redirect(`/search?q=${encodeURIComponent(keyword)}&page=1`);

其他方式

• middleware.ts里做条件重定向
• notFound()跳转到 404 页（严格说是「展示 404」，不是普通跳转）

调用 notFound() 时：

• URL 不会变成 /404，地址栏仍是 /posts/404-test
• Next.js 内部抛一个特殊的 NOT_FOUND 信号
• 渲染最近一层的 not-found.tsx

同类约定：error.tsx、loading.tsx也是按路由段就近渲染且 URL 不变，但触发方式不同——前者是运行时错误，后者是 Suspense 加载。

4. 跳转后如何获取参数

跳转时传的参数分两类：动态路由段（/posts/[slug]）和查询参数（?q=xxx）。

服务端（Server Component）

页面组件通过 props 接收：

// app/posts/[slug]/page.tsx interface Props { params: Promise<{ slug: string }>; searchParams: Promise<{ q?: string; page?: string }>; } export default async function Page({ params, searchParams }: Props) { const { slug } = await params; // 动态段：/posts/hello → slug = 'hello' const { q, page } = await searchParams; // 查询串：?q=nextjs&page=2 // ... }

Server Action 里可从formData或函数参数读取，再redirect到带参 URL。

客户端（Client Component）

"use client"; import { useParams, useSearchParams } from "next/navigation"; export default function SearchBar() { const params = useParams(); // { slug: 'hello' } const searchParams = useSearchParams(); const slug = params.slug as string; const q = searchParams.get("q"); // 'nextjs' 或 null const page = searchParams.get("page") ?? "1"; // ... }

useSearchParams()会使组件在客户端渲染；若只需在服务端读 query，优先用 Server Component 的searchParamsprop。

参数类型对照

速记

1. 能点链接就用<Link>，SEO 和预取都更好。
2. 事件里跳转用router.push/replace，记得'use client'。
3. 权限/校验在服务端用redirect，不暴露客户端逻辑。
4. 动态段用params，查询串用searchParams；客户端对应useParams/useSearchParams。