路由与页面组织
本合集目录
本章目录
单册说明:本文件是卷 4 的第 5 章,可独立阅读。前置:第 4 章(数据获取)。本章把单页应用拆成三条路由,并把"筛选条件"从内存搬进 URL——这一步决定了你的页面能不能被刷新、被分享、被后退。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 4 · React 与 Next.js(第 5 / 8 章) |
| 前置章节 | 4.4 副作用与数据获取 |
| 本章产出 | /、/notes、/notes/:id 三条路由 + 一个共享布局 + URL 驱动的筛选 |
| 对应代码 | src/pages/、src/components/Layout.jsx、src/main.jsx |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能解释"刷新 404 是服务器问题",并知道该改哪一行 |
4.5.1 一句话结论:路由不是换页面,是"URL 变了,我决定渲染哪棵树"
先看一个非常典型的故障:列表页点进详情,一切正常;看到地址栏是 /notes/n2,随手按 F5 想刷新一下,结果——
404 Not Found
本地 npm run dev 从来不这样,一部署就出现。很多人的第一反应是"路由配错了",然后把 path 改来改去,改到凌晨也没用。因为问题不在前端:F5 是浏览器向服务器要 /notes/n2 这个文件,而服务器磁盘上只有一个 index.html。
这一章要建立两个认知:路由是"URL 到组件树"的映射;URL 本身就是一份应该被认真对待的状态。
4.5.2 原理与方法
不刷新页面,怎么换内容
传统多页应用:点链接 → 浏览器发请求 → 服务器返回新的 HTML → 整页重建 → JS 状态清零。
单页应用(SPA):拦住点击 → 改地址栏 → 自己根据路径渲染对应组件。中间那步靠的是 History API:
| 方法 | 作用 |
|---|---|
history.pushState(state, '', '/notes/n2') |
改地址栏、压入一条历史记录、不发请求 |
history.replaceState(state, '', '/notes?tag=js') |
同上,但替换当前记录(后退不会多一步) |
popstate 事件 |
用户点前进/后退时触发,你需要监听并重新渲染 |
pushState 的三个动作里,第三点最关键:它不请求服务器。所以页面不刷新,JS 变量、滚动位置、正在播放的音频全都保得住。
也正因为不请求,F5 就破功了——地址栏是 /notes/n2,浏览器真的去要这个路径,服务器没有,404。
| 方案 | 地址长相 | 刷新是否 404 | 服务端能否看到路径 | 适合 |
|---|---|---|---|---|
| 多页(传统) | /notes/n2 |
否 | 能 | 内容站、需要 SEO |
| hash 路由 | /#/notes/n2 |
否 | 不能(只收到 /) |
快速原型、无服务端配置权限 |
| history 路由 | /notes/n2 |
是(未配置时) | 能 | 正经应用,需要配服务器回退 |
hash 的好处是"永远不会 404",因为 # 后面的部分浏览器不会发给服务器。代价是丑、服务端拿不到、某些统计工具会把它们算成同一个页面。本书用 history 路由,并且老老实实配服务器。
路由表就是一张映射
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/notes" element={<NotesPage />} />
<Route path="/notes/:id" element={<NoteDetailPage />} />
</Routes>
:id 叫动态段,能匹配 /notes/n1、/notes/abc,取出来永远是字符串。这一点会在坑二里引发一个很隐蔽的 bug。
嵌套路由与布局
三条路由都要有导航栏和页脚。复制三份能跑,但每次改导航要改三处——又是第 1 章那笔债。
<Route element={<Layout />}>
<Route index element={<HomePage />} />
<Route path="notes" element={<NotesPage />} />
<Route path="notes/:id" element={<NoteDetailPage />} />
</Route>
Layout 里用 <Outlet /> 占位:
import { NavLink, Outlet } from 'react-router-dom';
export default function Layout() {
return (
<div className="shell">
<header className="topbar">
<strong>读到</strong>
<nav>
<NavLink to="/" end className={({ isActive }) => (isActive ? 'active' : '')}>首页</NavLink>
<NavLink to="/notes" className={({ isActive }) => (isActive ? 'active' : '')}>摘录</NavLink>
</nav>
</header>
<main className="page"><Outlet /></main>
<footer className="foot">个人知识小站</footer>
</div>
);
}
好处不只是少写两段 HTML:切页时 Layout 不重新挂载,导航栏里的状态(比如展开的菜单、搜索框内容)不会丢。NavLink 的 end 是让 / 只在精确匹配时高亮,否则它会一直亮着。
还有一个细节:子路由的 path 不要写开头的 /。path="notes" 是相对于父路由的,写成 path="/notes" 就变成绝对路径,父级一换就断。这种错误不会报错,只会让某个页面永远匹配不到,然后你在"为什么点不进去"上耗掉一小时。
| 放在 Layout | 不放在 Layout |
|---|---|
| 导航、页脚、全局提示条 | 只在某一页出现的筛选器 |
| 需要跨页保持的滚动容器 | 页面级的数据请求 |
| 全局的登录态展示 | 页面标题(每页不同) |
URL 即状态:筛选条件该放哪
第 3 章的 activeTag 是 useState。它能用,但有四个说不出口的问题:
| 场景 | 放 state 的结果 | 放 URL 的结果 |
|---|---|---|
| 用户按 F5 | 回到"全部",他以为数据丢了 | 筛选还在 |
| 把链接发给别人 | 对方看到的是全部,不是你说的那一份 | 完全一致 |
| 点浏览器后退 | 直接退出站点 | 回到上一个筛选 |
| 看访问日志 | 只知道有人来了 /notes |
知道有多少人看了 tag=js |
所以筛选、排序、分页、搜索词,这类"用户希望能回到刚才那个视图"的信息,应该进 URL。表单草稿、弹窗开关、hover 状态则留在 state——它们不需要被分享。
代价是读写都变成字符串操作。useSearchParams 把这层包掉了:
const [searchParams, setSearchParams] = useSearchParams();
const activeTag = searchParams.get('tag') ?? 'all';
function changeTag(tag) {
setSearchParams(tag === 'all' ? {} : { tag });
}
注意 setSearchParams({}) 而不是 setSearchParams({ tag: 'all' }):让"全部"回到干净的 /notes,链接更好看,也不会出现 ?tag=all 和 /notes 两个内容相同但 URL 不同的页面。
还有一个选择:setSearchParams(next, { replace: true })。默认是 push,每切一次筛选就多一条历史记录,用户按后退会依次退回上一个筛选;用 replace 只替换当前记录,后退直接离开列表。哪个对取决于产品:把筛选当"视图"就用 replace,当"步骤"就用 push。本书用默认的 push,因为它让"我刚才看的是哪个标签"可以退回去。
切页之后,滚动位置要自己管
浏览器默认尽量保持滚动位置。从长列表滚到底部点进详情,详情页会停在一个奇怪的高度,用户以为内容缺失。
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
export default function ScrollToTop() {
const { pathname } = useLocation();
useEffect(() => {
window.scrollTo(0, 0);
}, [pathname]);
return null;
}
把它放进 Layout 里,它不渲染任何东西。依赖写 pathname 而不是整个 location:后者每次导航都是新对象,容易让你在不该滚的时候也滚一下。
刷新 404:一行配置的事,但要理解归因
| 现象 | 归因 | 修法 |
|---|---|---|
| 首页都打不开,404 | 文件真的没部署上去 | 检查 root 指向的目录 |
首页能开,点进 /notes 正常,F5 变 404 |
服务器没有 history 回退 | try_files $uri $uri/ /index.html; |
| 某个 id 打开是"未找到" | 路由匹配到了,但数据里没这条 | 查 id 类型与数据源 |
| 所有子路径都 404,连 JS 也 404 | 构建的 base 配错,资源路径前缀不对 |
检查 vite.config.js 的 base |
第二行就是本章开头那个故障。try_files 的意思是:先找这个路径的文件,再找目录,都没有就把 index.html 发回去,让前端路由自己处理。配置细节在卷 7,现在只要记住这是服务器的事,不是 React Router 的事。
还有一个容易误导人的点:vite preview 刷新不会 404,因为它自带 history 回退。所以"本地预览正常"完全不能证明线上正常。这个反差本身就是一堂课。
SPA 还有个先天缺陷:即使你显示了"页面不存在",服务器返回的状态码仍然是 200,搜索引擎会把它当成正常页面收录。要真正返回 404,得靠服务端渲染——4.6 里的 notFound() 就是干这个的。
4.5.3 动手:三条路由
装依赖并挂上 Router
npm install react-router-dom
src/main.jsx:
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import App from './App.jsx';
import './index.css';
createRoot(document.getElementById('root')).render(
<StrictMode>
<BrowserRouter>
<App />
</BrowserRouter>
</StrictMode>
);
BrowserRouter 放在最外层,整个应用才拿得到路由上下文。
App 变成路由表
src/App.jsx:
import { Routes, Route } from 'react-router-dom';
import Layout from './components/Layout';
import HomePage from './pages/HomePage';
import NotesPage from './pages/NotesPage';
import NoteDetailPage from './pages/NoteDetailPage';
import NotFoundPage from './pages/NotFoundPage';
export default function App() {
return (
<Routes>
<Route element={<Layout />}>
<Route index element={<HomePage />} />
<Route path="notes" element={<NotesPage />} />
<Route path="notes/:id" element={<NoteDetailPage />} />
<Route path="*" element={<NotFoundPage />} />
</Route>
</Routes>
);
}
path="*" 是兜底,别省。没有它,用户输错地址会看到一片空白,而不是"没有这个页面"。
列表页:筛选走 URL
src/pages/NotesPage.jsx:
import { useSearchParams } from 'react-router-dom';
import { allTags } from '../data/notes';
import { useNotes } from '../hooks/useNotes';
import TagFilter from '../components/TagFilter';
import NoteList from '../components/NoteList';
export default function NotesPage() {
const [searchParams, setSearchParams] = useSearchParams();
const activeTag = searchParams.get('tag') ?? 'all';
const { status, data, error } = useNotes(activeTag);
return (
<>
<h1>摘录</h1>
<TagFilter
tags={allTags}
activeTag={activeTag}
onChange={(tag) => setSearchParams(tag === 'all' ? {} : { tag })}
/>
{status === 'loading' && <p className="hint">加载中…</p>}
{status === 'error' && <p className="error">加载失败:{error}</p>}
{status === 'empty' && <p className="hint">这个标签下还没有摘录</p>}
{status === 'ready' && <NoteList notes={data} />}
</>
);
}
TagFilter 用的是第 2 章那个组件,只把 onChange 换成写 URL。这就是组件化的回报:换数据来源,组件不用动。
详情页:注意类型
先补一个单条的 hook,src/hooks/useNote.js,结构和第 4 章的 useNotes 一致:
import { useEffect, useState } from 'react';
import { fetchNote } from '../api/notes';
const initial = { status: 'loading', data: null, error: '' };
export function useNote(id) {
const [state, setState] = useState(initial);
useEffect(() => {
const controller = new AbortController();
setState(initial);
fetchNote(id, { signal: controller.signal })
.then((data) => setState({ status: 'ready', data, error: '' }))
.catch((err) => {
if (err.name === 'AbortError') return;
if (err.name === 'NotFoundError') {
setState({ status: 'empty', data: null, error: '' });
return;
}
setState({ status: 'error', data: null, error: err.message });
});
return () => controller.abort();
}, [id]);
return state;
}
NotFoundError 单独分流,是因为"没有这条摘录"不是故障,不需要显示红色错误;把它混进 error,用户会以为网站坏了。
src/pages/NoteDetailPage.jsx:
import { Link, useParams } from 'react-router-dom';
import { useNote } from '../hooks/useNote';
export default function NoteDetailPage() {
const { id } = useParams();
const { status, data: note, error } = useNote(id);
if (status === 'loading') return <p className="hint">加载中…</p>;
if (status === 'error') return <p className="error">{error}</p>;
if (status === 'empty') {
return (
<p>
没有这条摘录。<Link to="/notes">返回列表</Link>
</p>
);
}
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 to={`/notes?tag=${encodeURIComponent(t)}`}>{t}</Link>
</li>
))}
</ul>
<a href={note.sourceUrl} target="_blank" rel="noreferrer">查看原文</a>
<p><Link to="/notes">← 返回列表</Link></p>
</article>
);
}
useNote 与 useNotes 同构,只取一条,状态机一样(loading / error / empty / ready)。在 useNote 内部比较时用 String(n.id) === String(id),原因见坑二。
首页:给个入口
import { Link } from 'react-router-dom';
import { notes } from '../data/notes';
export default function HomePage() {
const recent = [...notes].sort((a, b) => b.createdAt.localeCompare(a.createdAt)).slice(0, 3);
return (
<>
<h1>读到</h1>
<p>把读到的句子存下来,按标签归档。</p>
<p>已收录 {notes.length} 条摘录。</p>
<h2>最近</h2>
<ul>
{recent.map((n) => (
<li key={n.id}><Link to={`/notes/${n.id}`}>{n.title}</Link></li>
))}
</ul>
<Link to="/notes">查看全部 →</Link>
</>
);
}
[...notes].sort(...) 而不是 notes.sort(...):后者会改原数组,虽然这里改的是模块级常量、暂时看不出问题,但这个习惯要养。
三个验证动作
- 切页不闪:点"摘录"再点"首页",页面不白屏、导航栏不重建(可以在
Layout里打个日志确认只打一次)。 - 刷新不丢:在
/notes?tag=js按 F5,筛选仍然是 js。把activeTag改回useState再试一次,会回到"全部"。 - 后退可用:点
js→ 点css→ 按浏览器后退,回到js;再后退,回到全部。
4.5.4 三个坑
坑一:用 <a href> 导航
症状:点导航栏,页面闪一下白,表单里填的内容全没了,Network 面板里多出一条类型为 document 的请求。
成因:<a> 的默认行为是让浏览器发起整页导航。你绕过了 pushState,整个 React 应用被卸载重建,所有内存状态清零。
修法:站内跳转一律用 <Link> 或 <NavLink>;只有指向外部站点时才用 <a>,并加 rel="noreferrer"。判断口诀:href 以 / 开头,就该是 Link。
坑二:useParams 给的是字符串
症状:详情页永远是"没有这条摘录",但列表点进去的 id 明明存在。改成别的数据又能对上一部分。
成因:useParams() 从 URL 里解析,URL 是文本,所以 id 是 "n2" 或 "1" 这样的字符串。如果你的数据里 id 是数字 1,notes.find((n) => n.id === id) 用严格相等永远为 false(1 === "1" 是 false)。
修法:统一比较的类型,别混着来。
// 数据 id 是字符串(本项目的做法)
const found = notes.find((n) => String(n.id) === String(id));
// 数据 id 是数字,且 URL 一定给数字
const num = Number(id);
const found = Number.isNaN(num) ? null : notes.find((n) => n.id === num);
不要图省事写 ==。它确实能让这个 bug 消失,但也会让 "" == 0 成立,埋下更难查的问题。
坑三:刷新 404,却去改前端路由
症状:本地开发一切正常,部署后首页能开、点进子页也能开,一按 F5 就 404;或者所有静态资源都 404,页面白屏但 HTML 有内容。
成因:前者是服务器没有把未知路径回退到 index.html;后者是构建时的 base 路径与实际部署目录不一致,资源请求打到了错误前缀上。
修法:前者在服务器加回退(Nginx 的 try_files $uri $uri/ /index.html;,其他托管平台找 "rewrites / SPA fallback" 配置);后者检查 vite.config.js 里的 base,部署在子目录时它必须匹配。先分清是哪一类,再去改配置——这两种 404 长得一样,修法完全不同。
本章验收
- 能说出
pushState做的三件事,以及为什么它会导致 F5 404 - 三条路由都通了,
*兜底能显示"页面不存在" - 筛选条件在 URL 里,刷新、分享、后退三个动作都正确
- 能解释
useParams为什么返回字符串,并写出正确的比较方式 - 能说出 404 的四种归因,以及各自的排查方向
自测
Q1:为什么 hash 路由"永远不会 404",但本书不用它?
看答案
因为 # 之后的部分浏览器不会发给服务器,服务端永远只看到 /,返回 index.html,前端自己解析 hash。代价是服务端完全不知道用户在看哪一页,SEO 和访问统计都拿不到真实路径,URL 也更长更丑。历史路由需要服务器配合回退,但换来干净的 URL 和可被服务端识别的路径。Q2:筛选条件放 URL 和放 state,最本质的区别是什么?
看答案
URL 是"可以被复制、被收藏、被后退、被服务端看到"的状态;state 只活在当前这个标签页的内存里。凡是用户希望"回到刚才那个视图"的信息(筛选、排序、分页、搜索词)都该进 URL;表单草稿、弹窗开关这类不需要分享的,留在 state。Q3:vite preview 刷新子路由正常,能证明线上也正常吗?
看答案
不能。vite preview 内置了 SPA 回退,任何未知路径都返回 index.html,所以它掩盖了服务器配置问题。线上用的是 Nginx 或别的静态服务器,默认没有这个回退。验证方法是部署后直接在子路由上按 F5,或者用 curl 请求 /notes 看返回的是 HTML 还是 404。下一步
三条路由在客户端跑起来了,但它们仍然是"浏览器先下载一个空壳,再画出来"。下一章换一套组织方式:文件夹就是路由,页面默认在服务器上渲染——这也是「读到」第一次真正拥有"首屏就有内容"的能力。