跳到正文
零到全栈 · 卷 4 · 从页面到应用

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),不是组件代码。

三个直接收益:

  1. 组件代码不进浏览器包,首屏 JS 更小;
  2. 可以直接 fs.readFile、查数据库、读 process.env 里的密钥;
  3. 组件可以是 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。

验证

  1. 访问 /、/notes、/notes?tag=js、/notes/n2,四条都通;
  2. 访问 /notes/不存在,显示 404 页面,用 curl -I 看状态码是 404;
  3. 右键"查看网页源代码",搜索"闭包",能直接搜到——说明内容在 HTML 里,不是 JS 渲染出来的;
  4. 打开 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 层:读文件、加缓存策略、用环境变量切换数据源——并且搞清哪些变量会被打进浏览器。

→ 卷4-07-数据获取缓存与环境变量.md