企业官网建设流程全解析

干了几年 React，路由是我见过最容易被低估的一个模块。很多项目第一天就接上了 react-router-dom，日常开发也就是写几个<Route>，但真到了上线前，刷新 404、菜单高亮错乱、权限路由绕来绕去，才意识到自己根本没有理解单页面应用（SPA）里这套“导航系统”的完整机制。这篇文章我会围绕 React 路由，把单页面应用的导航系统拆开揉碎，从核心原理讲到项目落地，再给出一份可以直接照着排查的问题速查表。适合刚接触路由的初学者、想系统梳理 React Router v6 的中级开发者，以及正在准备前端面试的同学。

1. 路由在单页面应用里到底解决了什么问题

1.1 多页面时代的痛点与 SPA 的体验优势

先退一步看一个很朴素的问题：为什么需要路由？

早年间做网站是典型的多页面应用（MPA），一个 URL 对应一个 HTML 文件，你在服务端渲染好整个页面再返回给浏览器。点击一个链接，浏览器发起新请求，整个页面白屏、加载、重新渲染，体验谈不上差，但确实有点笨重。SPA 出来之后，思路变了：首屏只加载一次 HTML 和 JS，之后用户点击链接、切换标签，都是纯前端在内存里替换视图，页面不再整页刷新，交互流畅得像桌面应用。

但问题也随之而来。SPA 只有一个index.html，如果什么都不做，用户不管点到哪里，地址栏始终停在同一个 URL。于是出现了三个很尴尬的场景：刷新后回到首页、浏览器前进后退完全失效、想复制一个页面链接发给同事，复制出来全是首页地址。

这三个问题，就是 React 路由和整个前端路由系统要解决的原始需求：让单页面应用的行为尽量接近多页面，把“当前看到了哪个页面”这个状态反映到 URL 上，并且同步管理浏览器的历史栈。React Router 在 React 生态里扮演的就是这个角色，它接管 URL 变化，把 URL 和组件视图做映射，让 SPA 里的“页面切换”变得可控、可追溯、可分享。

1.2 路由的核心机制：URL 与视图的映射

用一个类比理解 React 路由是什么：如果把单页面应用比作一本很厚的书，React Router 就是书前面的目录。你查目录的页码，翻到对应章节，目录本身不会重新打印一本书，只是帮你定位到要读的那一页。路由做的事就是“根据 URL 定位组件”，URL 变化时找到匹配的组件并渲染到页面上。

具体机制上，React Router 主要靠两套浏览器 API 兜底：

• hashchange事件：监听 URL 中#后面的变化，比如example.com/#/about。这种模式不重新请求页面，兼容性好，是老项目和静态托管的救星。
• History API：通过pushState、replaceState、popstate事件操作浏览器的历史记录，实现“无刷新改 URL”，这就是BrowserRouter的地基。

Router 内部维护了当前路径的解析结果，每次路径变化都会重新走一遍匹配流程：把最新 pathname 和已注册的路由表做匹配，选中最合适的 Route，渲染对应的 element。这套逻辑如果自己写，很容易遇到边界问题，比如路径带参、嵌套路由、通配匹配、优先级排序。React Router 把这些全部做成了声明式组件，用起来很简单，但底层的匹配算法一直在迭代，v6 里甚至换成了自动评分排序，解决了老版本里 Route 顺序决定匹配结果的坑。

2. React Router 核心 API 逐个击破

2.1 模式选型：BrowserRouter 与 HashRouter

这个选择几乎每个项目都会遇到。讲实话，很多人不假思索就上了BrowserRouter，网上搜到的大多是这个，代码跑起来没问题，结果部署到线上，用户一刷新，404。

两种模式最本质的区别在 URL 形式和服务器适配要求上，我直接列一个对照表：

我的建议是，如果团队能改服务端配置，优先BrowserRouter，URL 干净是长期的事；如果项目只是部署在一个对象存储或 CDN 上，后端又不归你管，直接用HashRouter，别硬扛。硬扛的结果就是线上出事，还得在深夜爬起来改配置。另外记住一点：HashRouter的 URL 里带#，在做埋点和分享时需要额外处理 hash 参数，很多人在这里栽过跟头。

2.2 Routes 与 Route：v6 的组件化路由配置

React Router v6 和 v5 最大的变化之一，就是Switch组件全面退场，换成了Routes。Routes的匹配逻辑是“自动评分”，它会遍历所有Route，根据路径的匹配程度打分，选分数最高的那一个渲染。这意味着你不用再像 v5 那样手动排列 Route 顺序，也不用担心path="/"把path="/about"拦截了。

一个最基础的路由配置长这样：

import { BrowserRouter, Routes, Route } from 'react-router-dom'; function App() { return ( <BrowserRouter> <Routes> <Route path="/" element={<Home />} /> <Route path="/about" element={<About />} /> <Route path="/users/:id" element={<UserDetail />} /> <Route path="*" element={<NotFound />} /> </Routes> </BrowserRouter> ); }

几个细节需要注意：

• element替代了 v5 里的component，传的是 React 元素而不是组件类，这样每个 Route 渲染时都可以独立传 props。
• path="*"是兜底通配，匹配所有未定义路径，通常用来渲染 404 页面。但注意它只能写在 Routes 内，不要指望*能跨层级处理子路由。
• 嵌套 Route 时，如果子路由的 path 不以/开头，它会基于父路由拼出相对路径。这个特性容易踩坑，我后面单独说。
• 路由组件在切换时并不会被卸载再重建，而是由 React Router 内部根据匹配结果保留或更新，所以组件里的 state 是否保留，取决于 Route 结构是否稳定。

2.3 Link、NavLink 与 useNavigate：三种跳转姿势

视图和 URL 的映射关系靠 Route 定义，那用户操作跳转靠什么？三种方式各有各的适用场景。

Link是基础版，它最终渲染成一个<a>标签，但 React Router 会在点击时拦截默认行为，改用 History API 更新 URL，避免整个页面刷新。它是“用户可点击跳转”的默认选择，比如文章链接、按钮跳转。

NavLink是Link的升级版，专门为导航菜单设计。它多了一个自动感知当前路径是否匹配的能力，配合className回调可以做高亮。这是我们后台管理系统侧边栏最常用的组件：

import { NavLink } from 'react-router-dom'; function Sidebar() { return ( <nav> <NavLink to="/admin/users" className={({ isActive }) => (isActive ? 'menu-item active' : 'menu-item')} > 用户管理 </NavLink> </nav> ); }

useNavigate是编程式导航用的。所谓“编程式”，就是你在逻辑代码里主动触发跳转，而不是用户去点链接。典型的场景是登录成功后跳到首页、表单提交成功后跳详情页：

import { useNavigate } from 'react-router-dom'; function LoginButton() { const navigate = useNavigate(); const handleLogin = () => { // 模拟登录成功 navigate('/dashboard', { replace: true }); }; return <button onClick={handleLogin}>登录</button>; }

replace: true的意思是替换当前历史记录，让用户按返回键不会回到登录页。这个细节在登录、支付成功这种场景特别重要，否则会出现“登出后点浏览器返回，又回到已失效的页面”的诡异问题。

3. 真实项目里的路由架构：从写 Demo 到能上线

3.1 嵌套路由与 Outlet：后台布局的骨架

实际项目里很少有那种“一个页面一个顶层 Route”的简单结构。后台管理系统是最典型的例子：整体是一个固定的 Layout（顶部栏、侧边栏、内容区），只有内容区随着路由变化而切换。这种场景靠标记名“写嵌套”是不行的，React Router 的模式是“父路由组件里留一个占位槽，子路由渲染到槽里”，这个槽就是Outlet。

先看路由定义：

<Route path="/admin" element={<AdminLayout />}> <Route index element={<Dashboard />} /> <Route path="users" element={<Users />} /> <Route path="settings" element={<Settings />} /> </Route>

再看AdminLayout：

import { Outlet } from 'react-router-dom'; function AdminLayout() { return ( <div className="admin-layout"> <aside className="admin-sidebar"> {/* 侧边栏菜单 */} </aside> <main className="admin-content"> <Outlet /> </main> </div> ); }

这个模式的关键就是Outlet。如果你忘了渲染Outlet，子路由即使匹配成功，也不会渲染出任何内容，页面看起来就是白得快光了，这是一个非常常见的“条件不渲染”的坑。

<Route index element={<Dashboard />} />里出现了index，它的意思是父路径/admin本身匹配时，默认渲染 Dashboard。这种“index 路由”在处理“默认页”时非常有用，等价于以前的path=""。

3.2 路由传参：params、query 与 state 怎么选

跳转时往往要带数据，React Router 提供了三种传参方式，搞混了会出现“刷新后参数不见了”的问题。

第一是 params 路径参数。适合表达资源层级，比如查看某个用户：/users/123。定义时写:id，组件里用useParams取：

<Route path="/users/:id" element={<UserDetail />} />

import { useParams } from 'react-router-dom'; function UserDetail() { const { id } = useParams(); // id = '123' }

第二是 query 参数，也就是 URL 问号后面的键值对，适合表达筛选条件、搜索关键词、分页信息，例如/users?page=2&keyword=react。v6 里推荐用useSearchParams，它和useState的用法很像：

import { useSearchParams } from 'react-router-dom'; function UserList() { const [searchParams, setSearchParams] = useSearchParams(); const page = searchParams.get('page') || '1'; const goNextPage = () => { const next = new URLSearchParams(searchParams); next.set('page', String(Number(page) + 1)); setSearchParams(next); }; return <button onClick={goNextPage}>下一页</button>; }

第三是 state 传参。这个不体现在 URL 里，而是存在 history 记录中，适合传非敏感、不需要分享的瞬态数据，比如“从哪个列表进入了详情页”：

navigate('/users', { state: { from: 'dashboard' } });

import { useLocation } from 'react-router-dom'; const location = useLocation(); console.log(location.state?.from); // 'dashboard'

三种方式怎么选，我自己的经验是：对用户可见、需要收藏和分享的参数，放 query；表达资源路径的，放 params；纯状态标记、丢失也没关系的，放 state。state 最大的坑是刷新页面后大概率就丢了（比如用户直接输入 URL 重新打开），如果刷新之后页面逻辑依赖这个值，就要考虑持久化方案，比如塞进 sessionStorage。

3.3 登录鉴权与路由守卫：没有守卫怎么办

Vue Router 里有一个非常直观的beforeEach导航守卫，可以在路由跳转前做登录判断。React Router v6 没有官方提供对应的守卫 API，但它完全可以用组件组合实现同样的效果，这也是 React 社区一贯的做法：用组件表达逻辑。

最常见的做法是封装一个RequireAuth包裹组件：

import { Navigate, useLocation } from 'react-router-dom'; function RequireAuth({ children }) { const { user } = useAuth(); const location = useLocation(); if (!user) { return <Navigate to="/login" state={{ from: location }} replace />; } return children; }

然后在路由配置里把它包在需要登录权限的路由上：

<Route path="/admin" element={ <RequireAuth> <AdminLayout /> </RequireAuth> } > <Route index element={<Dashboard />} /> </Route>

这里有两个细节值得一提。第一，Navigate一定要加replace，否则登录页会不断往历史栈里塞记录，点返回时会在“登录页和受保护页”之间死循环。第二，state={{ from: location }}记录了用户原本想去的地址，登录成功后可以读取这个值跳回去，体验上非常顺滑：

function LoginPage() { const navigate = useNavigate(); const location = useLocation(); const handleLogin = () => { // 登录逻辑... const from = location.state?.from?.pathname || '/dashboard'; navigate(from, { replace: true }); }; return <button onClick={handleLogin}>登录</button>; }

另外要提醒一句：前端路由守卫只是体验层的保护，真正的数据安全不能只靠它。接口权限必须由后端校验，否则别人绕过前端直接请求接口，照样能拿到数据。

3.4 按路由懒加载：让首屏不再“白屏等半天”

SPA 有一个天然问题：打包之后 JS 很大，如果首屏把所有页面的代码都加载完，用户会盯着白屏或 loading 很长时间。解决方案是按需加载，React 官方的组合就是React.lazy加Suspense。

import { lazy, Suspense } from 'react'; const Dashboard = lazy(() => import('@/pages/Dashboard')); const UserList = lazy(() => import('@/pages/UserList')); function App() { return ( <Suspense fallback={<div>页面加载中...</div>}> <Routes> <Route path="/" element={<Dashboard />} /> <Route path="/users" element={<UserList />} /> </Routes> </Suspense> ); }

lazy(() => import(...))会把对应模块单独拆成 chunk，只有当路由被访问时才加载。要注意lazy默认只支持默认导出（export default），如果你在页面文件里写成命名导出export function Dashboard()，代码会直接报错。解决办法是写一个默认导出再转发，或者干脆约定所有页面组件都用默认导出。

const Dashboard = lazy(() => import('@/pages/Dashboard').then((module) => ({ default: module.Dashboard })) );

还有一个小技巧：在 IDE 结合注释会清晰很多。webpack 会把webpackChunkName魔法注释变成 chunk 文件名，方便你在浏览器 Network 面板排查：

const Dashboard = lazy(() => import(/* webpackChunkName: "dashboard" */ '@/pages/Dashboard'));

4. 动态路由、菜单权限与约定式路由

4.1 后端菜单如何动态生成路由表

中小项目路由表写死在代码里没问题，但一旦做到后台管理系统，登录用户的权限不同，能看到的菜单和页面就不一样。常见的需求是后端下发菜单树，前端根据菜单动态渲染路由。这时如果还手写<Route>就没法维护了，更好的做法是把路由配置抽成数据，然后通过useRoutes统一渲染。

先定义一份“路由表”，每一项包含路径、渲染的组件、子菜单和元信息：

const routeMap = { dashboard: lazy(() => import('@/pages/Dashboard')), users: lazy(() => import('@/pages/Users')), settings: lazy(() => import('@/pages/Settings')), }; function buildRoutes(menus) { return menus .filter((item) => item.visible) .map((item) => ({ path: item.path, element: routeMap[item.component], children: item.children ? buildRoutes(item.children) : undefined, })); }

然后从后端拿到菜单数据，转成路由表：

import { useRoutes } from 'react-router-dom'; function AppRoutes() { const menus = useMenus(); // 从接口获取，可能来自 context const element = useRoutes(buildRoutes(menus)); return element; }

这种做法的好处是菜单、面包屑、路由三份数据共享同一份来源，不会再出现“页面能直接访问但菜单上没有入口”或者“菜单上有但路由没注册”的错位。但要注意，routeMap这个组件映射表是必须静态维护的，因为import()里的路径必须是字面量，不能用变量拼接，否则 webpack 无法静态分析、打不出独立的 chunk。

4.2 约定式路由：另一种思路

React Router 的组件式配置很灵活，但在大项目里也带来一个问题：每加一个页面就要手动改一次路由配置，漏改就会 404。约定式路由是另一种思路：约定优于配置，目录结构就是路由表，文件路径自动映射成 URL。

这个模式最典型的代表是 Next.js 和 Umi。比如在 Next.js 里，pages/about.tsx会直接映射成/about，pages/user/[id].tsx会映射成/user/:id。它对开发效率的提升非常直观，做中大型项目时团队不用再频繁维护路由配置。

React Router 本身不支持约定式路由，但可以通过工具链或脚手架引入。比如 Umi 底层虽然有自己的路由实现，但你仍然可以在项目里用 react-router-dom 的组件做二次开发。我个人的建议是：如果你在用 Next.js，跟着它的文件路由走，不要再尝试往里面嵌一套 React Router 路由；如果你在用 Vite + React，路由用 React Router 的声明式配置没毛病，想享受约定式路由的红利，可以关注一下 community 里基于文件系统生成路由的方案，但要评估好维护成本。

4.3 动态路径与刷新兜底：404 页别裸奔

动态路由通常指两种含义：一种是路径里有参数，比如/post/:id；另一种是运行时根据权限动态注册路由。无论哪种，都要处理“找不到页面”的情况。

路径参数的场景比较简单。定义一个带参数的 Route 后，组件里用useParams拿值，再根据值去请求数据：

<Route path="/post/:id" element={<PostDetail />} />

function PostDetail() { const { id } = useParams(); // 根据 id 请求文章详情 // 如果 id 不存在，渲染错误提示 }

这种场景下，一个非常容易被忽略的问题是“刷新后从 URL 拿参数”：id 在 URL 上所以没问题，但如果之前依赖页面 state 记录了列表页的筛选条件，刷新后这些条件全没了。所以做详情页时，最好把“这个页面属于哪个列表”这类信息也通过 query 带上，或者干脆重新拉取。

兜底 404 页则是必须要有的一层。用户可能手输 URL，也可能点了某个失效链接，如果连 404 都没设计，路由匹配不到时页面可能什么都不渲染，或者错误地匹配到父路由。我的做法是永远在路由表最后加一个path="*"的 404 页面，并且让它带一个“返回首页”的按钮，用户体验会好很多。

5. 常见问题与排查技巧实录

5.1 线上刷新 404：不是 React 的锅，是服务器的锅

这是BrowserRouter部署后排名第一的线上事故。现象特别典型：用户从首页点进/about一切正常，但只要一刷新，页面就变成 404 或 “Cannot GET /about”。原因很简单：静态服务器上没有/about这个文件，浏览器请求路径对应的资源，服务器找不到就返回 404。

解决思路是让服务器把所有未匹配的路径全部重写到index.html。Nginx 的配置一般是：

server { listen 80; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } }

关键就是try_files $uri $uri/ /index.html：优先尝试真实文件，找不到就回退到index.html。如果你的页面部署在子路径，比如https://example.com/app/，那还要给 BrowserRouter 配basename，同时 HTML 里的资源前缀也得对应调整，否则一样会出问题：

<BrowserRouter basename="/app">

<base href="/app/" />

如果确实没法改服务端配置，那就回到HashRouter，它不需要任何服务端兜底。

5.2 路由跳转了但组件不渲染

这个坑我在新手期踩过，也在别人的代码里见过好多次。表现是 URL 明明变了，页面却没动静。最常见的原因有这么几个：

• 父路由组件里没有写<Outlet />。嵌套路由必须靠 Outlet 渲染，漏了这个，子路由永远白搭。
• Route没有包在Routes里。v6 下 Route 必须作为 Routes 的直接或间接子组件，否则不生效。
• 组件渲染了但没内容。比如组件内部return null，或异步数据没回来就提前返回空值。
• 路由 path 写错了。很多人在嵌套路由里把子 path 写成了绝对路径，本意是/admin/users，结果子路由拼出来的路径变成了/admin/admin/users，自然匹配不上。

排查这类问题，我习惯先在浏览器地址栏直接输入一个目标 URL，看能不能命中；再去 React DevTools 里查看当前 Routes 的匹配结果；最后在组件里临时加一个console.log确认组件到底有没有被渲染。三步下来，基本能定位。

5.3 参数与状态丢失：useParams、searchParams、state 的坑

参数相关的问题，最常见的是“页面刷新后数据不见了”。如果数据是通过useLocation().state传的，刷新后大概率丢失，因为 state 存在内存里的 history 记录上，刷新后浏览器只保留了 URL，不会保留 state。解决办法是重要参数走 query 或重新请求。

useParams拿不到值的情况也有。比如你在子组件里调用useParams，但这个子组件不在对应 Route 的渲染树下，或者嵌套路由里父级和子级都定义了:id，你用useParams会拿到最近一级的匹配值，而不是所有级别。想拿父级的参数，得靠useMatch或从 context 传下来。

useSearchParams也要注意一点：它返回的每个值都是字符串，比如page=2拿到的就是"2"，做分页时注意转成 number。如果要更新多个参数，建议在原searchParams基础上复制一份再 set，避免把别的参数覆盖掉。

5.4 权限路由来回跳转：竞态与循环

权限路由的典型错误是“登录成功后页面一闪又跳回登录页”，或者“永远在登录页和首页之间来回跳”。常见原因有两个。

一是登录状态判断的时机不对。比如直接在用useAuth()里同步判断user是否为空，但实际上useAuth是从接口异步获取用户信息的，初始值为 null，路由一进来就认为未登录，立刻跳到登录页。等接口返回之后又变成了已登录，逻辑就乱了。解决思路是：在用户身份还在加载中时，渲染一个 loading 状态，不要急着做任何跳转判断。

二是Navigate没有用replace，或者跳转后没有清理 url 里残留的登录标记，导致历史栈里反复出现登录页。我的建议是：所有鉴权跳转统一加replace，跳转前把多余参数清干净。

还有一个容易忽略的小问题：如果RequireAuth里访问location的时候没有把完整对象传给 state，只传了一个 pathname，登录成功回跳时state.from.pathname就会拿不到。好一点的写法是直接保存整个location对象。

5.5 常见问题速查表

5.6 面试视角：路由这个点能问出什么深度

路由是前端面试的高频区，热词里 React 面试题、React 面经都经常带出这一块。我自己的感受是，面试官问 React 路由，通常不是考你 API 背得熟不熟，而是看你有没有理解它的底层机制。几个高频追问：

• v5 和 v6 最大的区别是什么？答：Routes 自动评分替换 Switch 的顺序匹配；useNavigate 替换 useHistory；Outlet 替换 children 嵌套；lazy 能力内置。
• BrowserRouter 和 HashRouter 的原理分别是什么？答：History API 和 hashchange 事件，以及各自的服务端适配要求。
• 为什么路由懒加载只支持默认导出？答：因为 import() 返回的是模块命名空间，React.lazy 要求拿到一个default属性作为组件。
• 嵌套路由的匹配规则是什么？答：父路径 + 相对子路径拼接，渲染时逐层匹配，每层通过 Outlet 承接。

把这些问题在项目里实际踩一遍、查一遍，比背面试题有用得多。

最后再分享一个我自己的习惯：路由表永远是项目里最不该乱的东西。无论项目大小，我都尽量把路由配置收敛成一个单一数据源，菜单、面包屑、权限都从它派生，而不是各写一份。这样加一个页面只动一处，改一个路径只改一处，线上排查问题时能省掉大量“对不上”的烦恼。路由这东西，用着简单，真正稳靠还是得靠架构上的克制。