Next.js 的 App Router
本合集目录
本章目录
单册说明:本文件是卷 4 的第 6 章,可独立阅读。前置:第 5 章(路由与页面组织)。本章换一套组织方式:不再写路由表,文件夹结构就是路由表;页面默认在服务器上渲染,浏览器只拿结果。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 4 · React 与 Next.js(第 6 / 8 章) |
| 前置章节 | 4.5 路由与页面组织 |
| 本章产出 | 用 App Router 重写的三条路由 + 五类特殊文件 + 一个叶子客户端组件 |
| 对应代码 | dudao-next/app/、components/、lib/notes.js |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能说清 'use client' 应该放在哪一层,以及放错会付出什么代价 |
4.6.1 一句话结论:文件夹就是路由,页面默认在服务器上跑
上一章的路由表是手写的:<Route path="notes/:id" element={...} />。App Router 把这张表变成了目录结构:
app/
├─ page.js → /
├─ notes/
│ ├─ page.js → /notes
│ └─ [id]/
│ └─ page.js → /notes/:id
新建一个文件夹,就多一条路由;删掉,路由就没了。没有第二处需要同步。
先记一个新手必踩的错:文件建好了,忘了默认导出。
Error: The default export is not a React Component in page: "/notes"
page.js 必须 export default 一个组件(可以是 async 函数)。命名导出不算。
4.6.2 原理与方法
路由由文件决定
| 文件路径 | URL | 说明 |
|---|---|---|
app/page.js |
/ |
根页面 |
app/notes/page.js |
/notes |
列表 |
app/notes/[id]/page.js |
/notes/n1 |
动态段,[id] 是变量名 |
app/notes/[id]/edit/page.js |
/notes/n1/edit |
嵌套 |
app/(marketing)/about/page.js |
/about |
括号是"分组",不进 URL,只用来共享布局 |
app/_components/Card.jsx |
无 | 下划线开头的文件夹不参与路由,用来放私有组件 |
最后两行值得记住:括号用于"给一组页面套同一个 layout,但 URL 里不出现这层";下划线用于"这个文件夹别当成路由"。两者都能减少无谓的目录层级。
五类特殊文件
| 文件 | 作用 | 必须是客户端组件吗 |
|---|---|---|
layout.js |
包住本段及所有子段,切页时不重建 | 否 |
page.js |
这一段可访问的页面 | 否 |
loading.js |
自动包一层 Suspense,子段加载时显示 | 否 |
error.js |
错误边界,捕获本段及子段的渲染错误 | 是(要用 reset) |
not-found.js |
404 界面 | 否 |
template.js |
类似 layout,但每次进入都重建 | 否 |
layout.js 和 template.js 的区别只有一句:layout 保留状态,template 不保留。做"进入页面时重置筛选"这类需求用 template,其余用 layout。
loading.js 是"免费"的:你什么都不用写,只要放一个骨架屏文件,Next 就会在这个段的数据还没好时先发它。这比手写 if (loading) return ... 早一步——用户在网络还没返回时就看到骨架,而不是白屏。
服务端组件与客户端组件
App Router 里,组件默认是服务端组件。它在服务器上执行,产出的是一段描述界面的数据(RSC payload),不是组件代码。
三个直接收益:
- 组件代码不进浏览器包,首屏 JS 更小;
- 可以直接
fs.readFile、查数据库、读process.env里的密钥; - 组件可以是
async,直接await数据。
代价是:没有状态、没有事件、没有浏览器 API。要用这些,就在文件顶部写 'use client'。
| 需要客户端组件 | 不需要 |
|---|---|
useState、useEffect、useReducer |
纯展示、拼 HTML |
onClick 等事件处理 |
读文件、查库、await 数据 |
window、localStorage、navigator |
格式化日期、拼字符串 |
| 依赖 DOM 的第三方库(图表、编辑器) | 用 Link 做导航 |
关键在"边界"两个字:'use client' 标记的是一个入口,从这个文件 import 下去的所有组件都会被打进客户端包。所以位置很重要。
| 放法 | 结果 |
|---|---|
放在 app/notes/page.js 顶部 |
整个页面连同列表、卡片全部变成客户端组件,白拿服务端渲染的好处没了 |
放在 components/NoteForm.jsx 顶部 |
只有表单进客户端包,列表和卡片仍在服务端渲染 |
口诀:把 'use client' 往下压,压到真正需要交互的那片叶子。
放错会立刻报错。比如在服务端组件里写事件:
export default function Page() {
return <button onClick={() => alert('hi')}>点我</button>;
}
Error: Event handlers cannot be passed to Client Component props.
React 不知道这个函数该怎么序列化给浏览器,所以直接拒绝。
同一条规则也约束 props:服务端组件传给客户端组件的值必须可序列化。对象、数组、字符串都行,函数不行——除非它是 Server Action(带 'use server')。所以 onDelete 这类回调不能从服务端页面直接传给客户端组件,得让客户端组件自己去调接口,或者把动作写成 Server Action。
布局嵌套与共享
根 layout 必须有 <html> 和 <body>,子 layout 不能有(否则 HTML 结构会嵌套错)。
// app/layout.js
export default function RootLayout({ children }) {
return (
<html lang="zh-CN">
<body>{children}</body>
</html>
);
}
导航时,layout 不重新渲染,只有 children 那一段换掉。所以放在 layout 里的 <audio> 不会被打断,侧边栏的滚动位置保得住,全局的 toast 容器也不会被销毁。
顺带说清一件事:导航时浏览器拿到的不是一整页新的 HTML,而是一段描述"哪部分变了"的数据。所以切页不会白屏,也不需要重新下载 layout。这是 App Router 和手写 SPA 最大的体感差别。
元信息也可以在服务端生成
页面级的标题用 export const metadata;动态页面要用 generateMetadata:
export async function generateMetadata({ params }) {
const { id } = await params;
const note = await getNote(id);
return { title: note ? note.title : '没有这条摘录' };
}
它和页面函数一样在服务端执行,所以能读数据。这样分享出去的链接,卡片上显示的是摘录标题,而不是站名。
动态段与 params
Next 15 起,params 和 searchParams 都是 Promise,必须 await:
import { notFound } from 'next/navigation';
import { getNote } from '@/lib/notes';
export default async function NoteDetailPage({ params }) {
const { id } = await params;
const note = await getNote(id);
if (!note) notFound();
return <h1>{note.title}</h1>;
}
忘了 await 不会崩,但控制台会警告:
Route "/notes/[id]" used `params.id`. `params` should be awaited before using its properties.
然后你拿到的是 undefined,页面显示"没有这条摘录"。这类"警告 + 错误结果"的组合最容易让人以为是数据问题。
searchParams 同理:
export default async function NotesPage({ searchParams }) {
const { tag = 'all' } = await searchParams;
const notes = await getNotes(tag);
return <NoteList notes={notes} />;
}
动态段不只有 [id] 这一种写法:[...slug] 能匹配多段路径(/notes/a/b/c),[[...slug]] 连空路径也匹配。本书用不到,但看到别人的项目里有方括号嵌套时不用慌——规则一样,只是匹配范围不同。
顺带一个会影响部署的副作用:一旦页面读了 searchParams,它就不能在构建时静态生成,因为结果依赖请求。这一点在 4.7 和 4.8 会变成具体的取舍。
Link 与导航
import Link from 'next/link';
<Link href="/notes">摘录</Link>
<Link href={`/notes?tag=${encodeURIComponent(tag)}`}>#{tag}</Link>
Link 会预取视口内的目标路由,点击时只做局部替换,不整页刷新。
需要编程式跳转时,在客户端组件里用 useRouter:
'use client';
import { useRouter } from 'next/navigation';
const router = useRouter();
router.push('/notes');
router.refresh(); // 重新拉取当前路由的服务端数据
注意包名是 next/navigation,不是 next/router(后者是旧的 Pages Router 用的,混用会报错)。
4.6.3 动手:把三条路由迁过去
建工程
npx create-next-app@latest dudao-next --js --eslint --app --no-src-dir --no-tailwind --import-alias "@/*"
cd dudao-next
npm run dev
参数含义:--js 用 JavaScript(不要 TypeScript),--app 用 App Router,--no-src-dir 让 app/ 直接在根目录,--no-tailwind 不加 CSS 框架,--import-alias 配好 @/ 指向项目根。
启动后访问终端给出的地址,看到 Next 的欢迎页。
数据层:先保持同步接口
新建 data/notes.js,内容与卷 4 第 2 章那份一致(notes 数组 + allTags)。
再建 lib/notes.js。这一章它只是包装,下一章会换成读文件:
import { notes, allTags } from '@/data/notes';
export async function getNotes(tag = 'all') {
return tag === 'all' ? notes : notes.filter((n) => n.tags.includes(tag));
}
export async function getNote(id) {
return notes.find((n) => String(n.id) === String(id)) ?? null;
}
export async function getTags() {
return allTags;
}
都是 async,因为下一章它们会变成真正的 I/O。现在就定好接口形状,后面换实现时页面不用改。
根布局
app/layout.js:
import Link from 'next/link';
import './globals.css';
export const metadata = {
title: '读到',
description: '个人知识小站:摘录、标签、检索',
};
export default function RootLayout({ children }) {
return (
<html lang="zh-CN">
<body>
<header className="topbar">
<strong>读到</strong>
<nav>
<Link href="/">首页</Link>
<Link href="/notes">摘录</Link>
</nav>
</header>
<main className="page">{children}</main>
</body>
</html>
);
}
metadata 是静态导出,Next 会把它渲染成 <title> 和 <meta>。这比客户端 document.title = ... 好在:爬虫和分享卡片拿得到,不需要等 JS。
首页与列表
app/page.js:
import Link from 'next/link';
import { getNotes } from '@/lib/notes';
export default async function HomePage() {
const all = await getNotes();
const recent = all.slice(0, 3);
return (
<>
<h1>读到</h1>
<p>把读到的句子存下来,按标签归档。</p>
<p>已收录 {all.length} 条摘录。</p>
<h2>最近</h2>
<ul>
{recent.map((n) => (
<li key={n.id}><Link href={`/notes/${n.id}`}>{n.title}</Link></li>
))}
</ul>
<Link href="/notes">查看全部 →</Link>
</>
);
}
注意它是 async 的,直接 await。这就是服务端组件最舒服的地方:没有 loading 状态、没有 effect、没有竞态,数据在发 HTML 之前就取好了。
app/notes/page.js:
import { getNotes, getTags } from '@/lib/notes';
import NoteList from '@/components/NoteList';
import TagFilter from '@/components/TagFilter';
export default async function NotesPage({ searchParams }) {
const { tag = 'all' } = await searchParams;
const [notes, tags] = await Promise.all([getNotes(tag), getTags()]);
return (
<>
<h1>摘录</h1>
<TagFilter tags={tags} activeTag={tag} />
<NoteList notes={notes} />
</>
);
}
Promise.all 让两个取数并行,而不是串行等待。它们互不依赖,没理由排队。
components/TagFilter.jsx 可以保持服务端组件,因为筛选只是一个链接:
import Link from 'next/link';
export default function TagFilter({ tags, activeTag }) {
return (
<nav className="filters">
<Link href="/notes" className={activeTag === 'all' ? 'active' : ''}>全部</Link>
{tags.map((tag) => (
<Link
key={tag}
href={`/notes?tag=${encodeURIComponent(tag)}`}
className={activeTag === tag ? 'active' : ''}
>
{tag}
</Link>
))}
</nav>
);
}
用 Link 做筛选,是这一章最划算的一个决定:筛选条件进 URL(第 5 章的理由全都在),组件不需要状态,也就不需要 'use client',整页仍然可以在服务端渲染完再发出去。
详情页与 404
app/notes/[id]/page.js:
import Link from 'next/link';
import { notFound } from 'next/navigation';
import { getNote } from '@/lib/notes';
import CopyLink from '@/components/CopyLink';
export default async function NoteDetailPage({ params }) {
const { id } = await params;
const note = await getNote(id);
if (!note) notFound();
return (
<article className="detail">
<h1>{note.title}</h1>
<p className="meta">{note.createdAt}</p>
<p>{note.content}</p>
<ul className="tags">
{note.tags.map((t) => (
<li key={t}>
<Link href={`/notes?tag=${encodeURIComponent(t)}`}>{t}</Link>
</li>
))}
</ul>
<a href={note.sourceUrl} target="_blank" rel="noreferrer">查看原文</a>
<CopyLink />
<p><Link href="/notes">← 返回列表</Link></p>
</article>
);
}
notFound() 会中断渲染并交给最近的 not-found.js。这比 return <p>没找到</p> 好:HTTP 状态码真的是 404,搜索引擎和监控都能识别。
app/not-found.js:
import Link from 'next/link';
export default function NotFound() {
return (
<div className="empty-page">
<h1>没有这个页面</h1>
<p>可能是链接过期,或者摘录已被删除。</p>
<Link href="/notes">回到摘录列表</Link>
</div>
);
}
一个真正的叶子客户端组件
详情页要一个"复制链接"按钮。它需要 useState 和浏览器 API,所以是客户端组件——但它足够小,不会把整页拖下水。
components/CopyLink.jsx:
'use client';
import { useState } from 'react';
export default function CopyLink() {
const [text, setText] = useState('复制链接');
async function handleClick() {
await navigator.clipboard.writeText(window.location.href);
setText('已复制');
setTimeout(() => setText('复制链接'), 1500);
}
return <button type="button" onClick={handleClick}>{text}</button>;
}
'use client' 必须在文件第一行(注释之外),前后不能有其他语句。
loading 与 error
app/notes/loading.js:
export default function Loading() {
return (
<div className="skeleton">
<div className="bar" />
<div className="bar" />
<div className="bar" />
</div>
);
}
app/notes/error.js 必须是客户端组件,因为它要用 reset:
'use client';
export default function NotesError({ error, reset }) {
return (
<div className="error-page">
<h2>这一页没加载出来</h2>
<p>{error.message}</p>
<button type="button" onClick={reset}>重试</button>
</div>
);
}
error.js 只捕获它这一层及以下的渲染错误,不会捕获 layout 里的错误——所以根 layout 出问题,需要 app/global-error.js。
验证
- 访问
/、/notes、/notes?tag=js、/notes/n2,四条都通; - 访问
/notes/不存在,显示 404 页面,用curl -I看状态码是 404; - 右键"查看网页源代码",搜索"闭包",能直接搜到——说明内容在 HTML 里,不是 JS 渲染出来的;
- 打开 Network,筛选 JS,页面文档的响应里已经有完整内容,首屏不依赖接口。
4.6.4 三个坑
坑一:在服务端组件里写事件或 hook
症状:页面直接编译失败,终端里一大段红字,核心是:
Error: Event handlers cannot be passed to Client Component props.
或者:
You're importing a component that needs `useState`. This only works in a Client Component but none of its parents are marked with "use client", so they're Server Components by default.
成因:服务端组件的产物要跨网络传给浏览器,函数无法序列化。React 干脆在构建期就拦住。
修法:把需要交互的那一小块抽成独立文件,顶部加 'use client',再在服务端组件里像普通组件一样使用。不要图省事给整个 page.js 加 'use client'——那会让整页退化成客户端渲染,这一章讲的好处全丢。
坑二:忘了 await params
症状:详情页永远显示 404;控制台有一条警告,内容是 Route "/notes/[id]" used `params.id`. `params` should be awaited before using its properties.;console.log(params) 打印出一个 Promise。
成因:Next 15 起 params 和 searchParams 改成了 Promise,支持流式渲染。老写法 params.id 拿到的是 undefined,于是 getNote(undefined) 返回 null,页面走 404。
修法:const { id } = await params;。同样别忘了 searchParams。如果页面组件不是 async,改成 async 即可。
坑三:客户端组件在渲染期间碰 window
症状:npm run build 失败,或者页面首屏报:
ReferenceError: window is not defined
成因:客户端组件也会在服务器上预渲染一次(生成首屏 HTML)。那次执行发生在 Node 里,没有 window、没有 localStorage。你在函数体里直接读它们,就会在构建或首屏阶段炸掉。
修法:把浏览器相关的读写放进 useEffect(它只在浏览器执行),或用事件触发。
'use client';
import { useEffect, useState } from 'react';
export default function ThemeBadge() {
const [theme, setTheme] = useState('light');
useEffect(() => {
setTheme(localStorage.getItem('theme') ?? 'light');
}, []);
return <span>{theme}</span>;
}
typeof window !== 'undefined' 的守卫也能让它不报错,但首屏会渲染出与服务端不一致的内容,容易引发 hydration 警告。能放 effect 就放 effect。
本章验收
- 能画出
app/目录树,并说出每个文件对应的 URL - 三条路由都通了,
/notes/不存在返回真正的 404 状态码 - 能说出
'use client'的正确位置,并举一个"放错层"的后果 - 详情页的复制按钮可用,且页面其余部分仍是服务端组件
- 查看源代码能看到摘录正文,不依赖 JS
自测
Q1:为什么 App Router 默认让组件在服务端渲染?它牺牲了什么?
看答案
收益是首屏 HTML 直接带内容、浏览器下载的 JS 更少、能直接读文件和密钥。牺牲的是交互能力:服务端组件不能用状态、事件和浏览器 API,也不能把函数当 props 传给别的服务端组件。所以设计上要把交互压到叶子节点,用 'use client' 划一条尽量小的边界。Q2:layout.js 和 template.js 都能包住子页面,什么时候必须用后者?
看答案
当"每次进入这个段都需要重置内部状态"时。layout 在导航时保留实例,里面的 useState 不会回到初始值;template 每次进入都重新挂载,状态自然重置。典型场景:进入不同详情页时要清空上一条的评论草稿、重新播放进入动画、重新上报一次曝光。Q3:一个页面读了 searchParams,会对部署方式产生什么影响?
看答案
它变成动态渲染:结果依赖每次请求的查询串,无法在构建时生成一份固定的 HTML。这本身不是错,但意味着你不能用纯静态托管,必须有 Node 进程在每次请求时渲染(或者接受它被降级为客户端渲染)。这也是 4.8 选择上线方式时的关键判断之一。下一步
页面已经能在服务器上渲染了,但数据还是写死在 data/notes.js 里。下一章把数据搬到一个真正的 data 层:读文件、加缓存策略、用环境变量切换数据源——并且搞清哪些变量会被打进浏览器。