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

路由与页面组织

本合集目录
本章目录

单册说明:本文件是卷 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(...):后者会改原数组,虽然这里改的是模块级常量、暂时看不出问题,但这个习惯要养。

三个验证动作

  1. 切页不闪:点"摘录"再点"首页",页面不白屏、导航栏不重建(可以在 Layout 里打个日志确认只打一次)。
  2. 刷新不丢:在 /notes?tag=js 按 F5,筛选仍然是 js。把 activeTag 改回 useState 再试一次,会回到"全部"。
  3. 后退可用:点 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。

下一步

三条路由在客户端跑起来了,但它们仍然是"浏览器先下载一个空壳,再画出来"。下一章换一套组织方式:文件夹就是路由,页面默认在服务器上渲染——这也是「读到」第一次真正拥有"首屏就有内容"的能力。

→ 卷4-06-Next的App-Router.md