企业官网建设流程全解析

打开一个真实的业务项目，路由这块从来不是“配几个 path 就够了”的事。登录态校验、角色权限、订单页/后台页/个人中心各自不同的访问边界，还有登录之后跳回原页面的体验问题，这些需求堆在一起，前端迟早要面对一个统一的出口来做拦截校验。React Router 7 是我最近在一个中后台模拟项目 X 里实测完的版本，它的路由模型和 v6 大体一致，但在数据路由、loaders、redirect 这些机制上更顺手。这篇文章我就围绕“React Router 7 全局路由保护”这个主题，把我在项目里的设计思路、完整实现、以及调试时踩过的坑一起整理出来。

先说我最终采用的保护方案：用 createBrowserRouter 创建数据路由，在根布局的出口位置做统一守卫层，配合 React Context 里的用户状态机，做到“全局拦截、全局放行、按权限定向”。整个方案不依赖任何第三方鉴权库，所有代码都是 React Router 7 原生能力 + 自管理状态，适合中小型项目直接落地，也方便你替换成自己的真实鉴权逻辑。

1. React Router 7 路由保护的核心思路

1.1 为什么前端必须有全局路由守卫

很多刚接触权限系统的同学会问：后端接口已经做了权限校验，前端做路由守卫是不是多此一举？答案是否定的。后端校验管的是“数据能不能拿”，前端路由守卫管的是“页面能不能进”。如果没有前端拦截，未登录用户虽然拿不到接口数据，但页面框架、布局、静态资源已经加载出来了，敏感模块的代码也可能被直接打包送达浏览器，这本身就是一种信息暴露。而且从体验上讲，用户访问受保护页面被后端 401 打回来，和前端直接跳去登录页，完全是两种感受。

所以我的理解是：前端路由守卫承担的是“访问控制 + 体验兜底”的双重职责。它保证未授权的人在进入页面组件渲染之前就被拦住，而不是先看到一屏残缺内容再去处理错误。React Router 7 里，这个拦截动作可以放在 router 配置层，也可以放在组件渲染层，两种各有优劣，我下面会展开对比。

1.2 新版路由模型下的方案选型

React Router 7 依然保留了两种路由使用模式：声明式（用 BrowserRouter、Routes、Route 写 JSX）和数据路由（用 createBrowserRouter 创建 router 对象，再交给 RouterProvider）。旧项目里大多数人习惯的是声明式写法，组件内用<Navigate>或者 useNavigate 做跳转，也能实现守卫。但如果你要做的是“全局统一拦截”，我更建议直接切换到数据路由模式。

原因有三个。第一，createBrowserRouter 可以集中管理路径配置、loader、错误边界，路由结构一目了然。第二，React Router 7 的 loader 机制天然支持“在渲染页面组件之前执行逻辑”，这跟守卫的语义完全吻合。第三，数据路由模式下，根路由的 outlet 位置可以插入一个统一守卫组件，让所有子路由在渲染前经过同一道闸门。而声明式写法里，守卫组件只能一层一层地包，遇到嵌套路由就很啰嗦。

我在模拟项目 X 里最终采用的是“根路由出口守卫”方式，不单纯依赖 loader，因为 loader 里能访问的重定向能力虽然强，但和组件内部的状态管理联动不够方便。守卫组件直接挂在根路由上，相当于给整棵路由树装了一个前置过滤器，全局性最强。

2. 全局路由保护的详细设计与实现

2.1 三个关键问题：拦截什么、放行什么、跳到哪

动手之前，先把需求问清楚。全局路由保护至少要回答三件事：

1. 拦截什么：哪些路径必须登录才能访问。
2. 放行什么：登录页、注册页、404 页面这些公共入口应该直接访问。
3. 跳到哪：未登录用户访问受限页时，是去登录页还是去首页；登录成功之后，是留在登录页还是回到用户原本想去的页面。

我拿模拟项目 X 举例，它的页面分为三类：公共页（登录、注册、忘记密码）、普通用户页（首页、个人中心）、管理员页（后台管理、数据报表）。普通用户页要求登录，管理员页要求登录且角色是 admin。这个需求看起来简单，但实际操作时你会发现，“判断是否登录”这个动作本身可能是异步的，比如要从本地存储读 token，再用 token 请求用户信息。如果这个异步过程没处理好，很容易出现页面闪一下白屏或者把已登录状态误判成未登录。后面我会专门讲怎么用状态机解决这个问题。

2.2 数据路由模式下的全局守卫组件怎么写

先看完整代码骨架。我用 createBrowserRouter 创建路由，根路由不直接指向页面组件，而是指向一个叫 RootLayout 的布局组件，这个组件内部就嵌着全局守卫逻辑。代码如下：

import { createBrowserRouter, RouterProvider, Outlet, Navigate, useLocation, useNavigate } from "react-router-dom"; const router = createBrowserRouter([ { path: "/", element: <RootLayout />, errorElement: <NotFoundPage />, children: [ { index: true, element: <HomePage /> }, { path: "login", element: <LoginPage /> }, { path: "register", element: <RegisterPage /> }, { path: "user", element: <UserCenterPage /> }, { path: "admin", element: <AdminPage /> }, { path: "*", element: <NotFoundPage /> }, ], }, ]); function RootLayout() { return <GlobalGuard><Outlet /></GlobalGuard>; }

RootLayout 本身不做任何拦截，真正的拦截逻辑在 GlobalGuard 组件里。这样做的理由是：根路由的 Outlet 是所有子路由页面的渲染出口，任何子路由切换时，GlobalGuard 都会重新执行渲染逻辑。换句话讲，整个应用就像只有一个大门口，任何人想进任何房间都得先过门口保安这一关。

再看 GlobalGuard 的核心实现：

import { useContext, ReactNode } from "react"; import { useLocation, Navigate } from "react-router-dom"; import { AuthContext } from "@/store/auth"; const publicPaths = ["/login", "/register"]; function GlobalGuard({ children }: { children: ReactNode }) { const { status } = useContext(AuthContext); const location = useLocation(); // 状态机：verifying 表示正在恢复登录态 if (status === "verifying") { return <FullScreenLoading />; } const isPublic = publicPaths.includes(location.pathname); // 未登录访问公共页：放行 if (isPublic) return <>{children}</>; // 未登录访问受保护页：跳登录，并记录来源 if (status === "anonymous") { const redirect = encodeURIComponent(location.pathname + location.search); return <Navigate to={`/login?redirect=${redirect}`} replace />; } // 已登录回访登录页：直接送首页 if (location.pathname === "/login" && status === "authenticated") { return <Navigate to="/" replace />; } return <>{children}</>; }

这段代码的巧妙之处在于，它把“全局”两个字落到了实处：publicPaths 数组就是白名单，任何不在名单里的路径都会被视为需要登录。如果你想对某个路径做特殊角色控制，也可以在这个组件里再加一层 role 判断，后面我会讲到。

2.3 为什么不用 useEffect + useNavigate 做守卫

很多同学看到这种场景，第一反应是写一个 useEffect 监听登录状态变化，然后调用 useNavigate 跳转。这在我早期项目里也用过，但最终放弃了。典型写法是这样的：

useEffect(() => { if (status === "anonymous") { navigate("/login"); } }, [status, navigate]);

这种写法最大的问题在于：副作用的发生时机晚于渲染时机。组件已经进入渲染流程了，useEffect 才在浏览器执行阶段触发跳转。这就意味着受保护页面的组件可能已经渲染了一帧甚至更多帧，用户会看到页面内容一闪而过，然后才被甩到登录页。更麻烦的是，如果你的页面组件里还有数据请求，这些请求也会在跳转前发出去，白白浪费流量，极端情况下还会报错。

而 GlobalGuard 的处理方式完全不同：它直接在渲染期做判断，用<Navigate>声明式地返回跳转结果。React Router 会把<Navigate>当作一次渲染输出处理，跳转发生在页面真正展示之前。所以在体验上，用户不会看到受保护页面闪现。这就是我推荐这种方案的核心原因：用渲染期判断替代副作用跳转。

2.4 状态管理：用“三态”代替“布尔”判断

我在代码里用了 status 字段，取值是 verifying、anonymous、authenticated 三种。这是整个方案里最容易被忽略、也最容易出问题的一环。

很多权限方案习惯用 isLoggedIn 这种 boolean，或者 token 是否为空来区分登录态。问题是：判断登录态可能是一个异步过程。比如用户刷新页面后，你拿到 token，还得用 token 去换取用户信息，这个请求最快也要几十毫秒。如果用 boolean 表达，初始值是 false，那你无法区分“正在恢复登录态”和“真的未登录”。结果就是用户明明已经登录了，刷新后却被当成游客踢回登录页。

三态状态机就是为了解决这个问题。逻辑非常简单：

1. 应用启动时，status 初始化为 verifying，同时后台尝试恢复登录态。
2. 恢复成功，status 变成 authenticated。
3. 恢复失败（没有 token 或 token 失效），status 变成 anonymous。
4. 在 verifying 阶段，GlobalGuard 不判断放行还是拦截，直接渲染全屏 Loading。

用代码描述就是这样：

function AuthProvider({ children }: { children: ReactNode }) { const [state, setState] = useState<{ status: AuthStatus; user: UserInfo | null }>({ status: "verifying", user: null, }); useEffect(() => { const token = localStorage.getItem("token"); if (!token) { setState({ status: "anonymous", user: null }); return; } // 模拟：异步请求用户信息 fetchUserInfo(token) .then((user) => setState({ status: "authenticated", user })) .catch(() => { localStorage.removeItem("token"); setState({ status: "anonymous", user: null }); }); }, []); const login = async (formData: any) => { const { token, user } = await loginRequest(formData); localStorage.setItem("token", token); setState({ status: "authenticated", user }); }; const logout = () => { localStorage.removeItem("token"); setState({ status: "anonymous", user: null }); }; return <AuthContext.Provider value={{ ...state, login, logout }}>{children}</AuthContext.Provider>; }

我不建议把用户信息分散存到各个页面各自的 state 里，那样守卫层就没法统一校验角色了。用户信息必须挂在一个全局 Context 下，让 GlobalGuard 可以直接拿到 role 字段。

3. 实操笔记：一个完整项目中的路由护层

3.1 带角色的守卫扩展

模拟项目 X 里有一个管理员页面，只有 admin 角色能访问。在 GlobalGuard 基础上扩展并不难，只需要在放行逻辑前增加角色判断。我会把角色判断独立成一个函数：

function canAccess(pathname: string, role: string | null): boolean { if (pathname.startsWith("/admin") && role !== "admin") { return false; } return true; }

然后在 GlobalGuard 主体里，在确定已登录之后调用这个函数：

if (status === "authenticated") { const allowed = canAccess(location.pathname, user?.role ?? null); if (!allowed) { return <Navigate to="/403" replace />; } return <>{children}</>; }

这样做的好处是，权限规则集中在守卫层，页面组件内部只需要关注自己的业务逻辑，不需要关心“我有没有权限渲染”。我在项目里还约定：所有受保护页面都不再做二次权限校验，完全相信守卫层。这个约定大大简化了页面代码。

角色判断的时候要注意路径前缀的边界问题。比如你用pathname.startsWith("/admin")判断，那/administer这样的路径也会被拦下来。我项目里为了避免误伤，统一约定所有后台页面都挂在/admin前缀下，并且子路径不允许直接拼接相似前缀。如果你也有这种路径边界担忧，更精确的方案是把角色权限配置成一张表，而不是写死在路径判断里。

3.2 登录回跳逻辑的完整闭环

我在前面提到，未登录用户会被带到/login?redirect=%2Fuser%3Ftab%3Dorder这个地址。这个细节如果做得不好，用户的体验会非常割裂：他明明想进个人中心的订单页，登录完却看到的是首页，还得重新点一次。

登录页拿到 redirect 参数后，在登录成功回调里做处理：

function LoginPage() { const [searchParams] = useSearchParams(); const redirect = searchParams.get("redirect"); const { login } = useContext(AuthContext); const navigate = useNavigate(); const onSubmit = async (values: any) => { await login(values); if (redirect) { navigate(decodeURIComponent(redirect), { replace: true }); } else { navigate("/", { replace: true }); } }; }

这个逻辑的要点有两个。第一，redirect 参数必须做 encodeURIComponent 编码，因为用户原本访问的路径可能自带 query 参数，比如/user?tab=order，如果不编码，URL 就会变成/login?redirect=/user?tab=order，解析时容易乱套。第二，登录成功后的跳转要用 replace 而不是 push，这样用户按返回键不会又回到登录页，体验上更自然。

我在实际项目里遇到的另一个问题：未登录用户访问的是根路径/，那 redirect 参数就是空字符串，这时我上面代码里navigate(decodeURIComponent(redirect))会跳去一个空路径，React Router 会解析成相对路径，容易出问题。所以必须判断 redirect 是否为空，再决定跳回地址，否则就是一个隐形的坑。

3.3 动态路由与懒加载在守卫中的配合

模拟项目 X 里，后台管理页是几个不同角色共用的一套布局，但具体菜单项不一样。实现时我把动态菜单和路由懒加载结合了起来，在守卫层不直接渲染全部子页面，而是在状态恢复完成后，根据用户角色动态组装菜单数组。

这里要提一个和路由保护相关的细节：动态路由如果放在 children 里让 router 自行匹配，那么懒加载的组件在首次加载时可能会让用户感知到延迟。我的做法是，在守卫组件里渲染一层 Suspense，配合懒导入的页面组件，让路由切换更平滑：

import { Suspense, lazy } from "react"; const AdminDashboard = lazy(() => import("@/pages/admin/Dashboard")); const AdminUserList = lazy(() => import("@/pages/admin/UserList")); function AdminLayout() { return ( <Suspense fallback={<div style={{ padding: 24 }}>页面加载中...</div>}> <Outlet /> </Suspense> ); }

很多项目会把 Suspense 和守卫分开处理，但我建议把懒加载边界放在守卫之后，因为只有当用户确实有权访问这个页面时，才该去加载这个页面代码。这个顺序能减少不必要的资源请求，尤其对体积比较大的后台页面来说，收益很明显。

动态路由还有一个常见的坑：路由配置里如果没有兜底path: "*"，用户手动修改 URL 访问一个不存在的路径时会直接报错，React Router 7 的默认行为是渲染错误边界。为了让 404 页面可控，我在 router 配置的 children 最后加了一个通配路由：

{ path: "*", element: <NotFoundPage /> }

注意这个通配路由也挂在根路由的 children 里，所以它同样会经过 GlobalGuard。但有一个问题：未登录用户访问一个不存在的受保护路径，是先去登录页还是先看 404？我的预期是：优先登录。所以 GlobalGuard 的判断顺序是先判断“是否公共路径”，再判断“是否已登录”，最后才轮到 Router 内部去匹配最终路由。这意味着即使路径本身不存在，未登录用户也会被送去登录页，而不是直接看到 404。这个顺序在项目里是刻意为之的，因为对业务系统来说，隐藏“路径是否存在”本身就是一种安全措施。

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

4.1 页面闪一下再跳走，怎么定位守卫时机

这是路由保护最常见的毛病。我在模拟项目 X 早期版本就遇到过：用户未登录访问/user，页面先渲染出一部分用户中心的内容，然后才跳去登录页。排查下来发现是两处原因叠加导致的。

第一处是守卫组件用 useEffect 做跳转，这个我在前文已经批评过了，改掉它，用渲染期<Navigate>。第二处是状态恢复逻辑有问题：用户没有 token 时，status 从 verifying 变成 anonymous 的过程有延迟，在这段时间里 GlobalGuard 走的是 loading 分支，按理说不会渲染子页面。但如果你的 AuthProvider 初始化没有设置 verifying，而是直接把 status 初始化为 anonymous，那首次渲染时子页面就会先出现。

最稳的做法是：把状态恢复逻辑放在应用初始化阶段，并且在 GlobalGuard 里明确返回全屏 loading。代码里我写了if (status === "verifying") return <FullScreenLoading />，这一行直接把“闪烁问题”消灭在源头。FullScreenLoading 本身要足够轻量，不要发起任何请求，不要在内部渲染 Outlet。

还有一个隐藏点：多个并发的页面同时处于加载中，全屏 Loading 覆盖层可能需要设置一个最小展示时间，避免出现“闪白”太快导致用户以为页面坏了。我是在 CSS 里给 loading 层加了一个淡入效果，视觉上更平滑，代码上没有任何复杂度提升。

4.2 循环重定向（登录后一直跳登录）

有一次我调试时发现，用户登录成功后居然又弹回登录页，而且 repeat 循环了几次浏览器地址栏才开始稳定。排查后发现，问题出在登录页自身的守卫逻辑和登录成功后的跳转逻辑互相冲突。

场景是这样的：GlobalGuard 里判断“已登录访问 /login 就跳去首页”，这个逻辑本身没问题。但登录页派发 login 操作后，状态尚未更新，这时候登录页还在 /login 地址上。React 的 setState 是异步的，如果我在 onSubmit 里同时调用了 login() 和 navigate("/")，状态更新和导航更新可能交错执行，导致 React Router 先渲染了新路由 /，但这时 GlobalGuard 还读到旧的 anonymous 状态，结果又把人抬回 /login。

解决思路是把这两个动作拆开：先执行 login()，等状态真正更新到 authenticated 之后，再让 GlobalGuard 的“已登录访问登录页跳首页”这一分支自然接管。也就是 onSubmit 里只调 login()，不手动 navigate。因为当状态变成 authenticated 后，GlobalGuard 会重新渲染当前路由 /login，发现自己已登录且当前是公共页，就会自动跳去 / 或者 redirect 参数指定的页面。

那 redirect 参数怎么带过去？可以把 redirect 参数放到 Context 或者模块级变量里，GlobalGuard 在跳转时直接读取。这个方案比我手动 navigate 要干净得多，也避开了循环跳转问题。如果你更倾向于手动 navigate，那必须保证 login() 返回的 Promise 在状态更新完成后再 resolve，或者干脆不要手动 navigate，彻底让守卫层来接管。

4.3 异步用户信息恢复期间的白屏

项目上线后，有用户反馈：刷新页面偶尔会白屏一秒多，尤其是网络慢的时候。原因很直接：verifying 状态要等 fetchUserInfo 请求返回，这个期间的 FullScreenLoading 一直占据屏幕，虽然不算白屏，但等待感很强。

我的优化办法是给 FullScreenLoading 加一个超时兜底和骨架屏样式。如果 3 秒内用户信息还没恢复，就渲染一个带品牌信息的静态页，而不是全屏 spinner。同时，如果本地根本没有 token，就直接跳过 fetchUserInfo，立刻进入 anonymous，避免无谓的网络请求延迟。

另一个优化点是把用户信息的本地缓存与请求结果结合。刷新时先用缓存渲染页面框架，后台再用请求结果校验缓存是否有效。如果缓存失效，再强制登出。这套逻辑稍微复杂一点，但在企业应用中非常值得做，因为用户体验差距非常大。我在这篇文章里只实现了一个最简单的版本，你可以根据自己的项目需求扩展。

4.4 查询参数丢失导致跳到空白页

这个坑说小不小。未登录用户访问/user?tab=order，守卫层生成/login?redirect=%2Fuser%3Ftab%3Dorder，登录成功回跳时解析参数。如果解析或编码不一致，可能出现两种情况：一是回跳时把 query 丢了，用户看到的是/user而不是原来的 tab；二是回跳时 query 解析错乱，比如把登录页的 redirect 参数当成自己页面的参数，页面直接空白。

我的排查结论是：编码动作最好在生成 redirect 的那一刻统一，使用encodeURIComponent，解析时使用decodeURIComponent。不要一个环节编码一次、另一个环节又用 searchParams.get 拿原始值再编码。只要保证编码/解码配对，这个问题基本不会出现。

还遇到过一种边缘情况：redirect 参数里本身带特殊字符（如中文搜索词、嵌套斜杠），在部分浏览器地址栏里会被自动解码，导致登录页拿到 redirect 后第二次编码，最终访问的地址不符合预期。解决办法是：GlobalGuard 生成 redirect 时不使用 searchParams 重新编码，而是把整个相对路径（pathname + search）直接编码一次。登录页解析时也只用一次 decode，不要二次解码。

5. 我实测下来的一些偏好

React Router 7 的全局路由保护，说实话核心代码不多，几十行就能搞定。但真正决定方案好坏的，往往是你对状态的建模和对跳转时机的把控。我在模拟项目 X 里做过的几次重构，基本都是围绕“状态有没有可能误导守卫”这个点展开的。

我最常用的小技巧是控制台可视化状态变化。调试守卫时，我在 AuthProvider 里临时加了一行日志，把 status 的每次变化打印出来。这个日志在本地开发环境能帮我快速确认到底是因为状态还没恢复、还是因为状态被错误更新成 anonymous，才导致跳转异常。排查效率比瞎猜高很多。

如果你准备在一个新项目里落地这套方案，我的建议是：先把 AuthContext 和 GlobalGuard 搭好，跑通“未登录访问受限页跳登录、登录后回跳原页”这条链路。这条链路通了，再逐步扩展角色判断、动态路由、懒加载优化。权限这块最怕一上来就搞得很复杂，层层嵌套守卫，出了问题反而不好定位。小而稳，再逐步外扩，是我比较推荐的方式。