React / 系统课时
路由守卫与异常页面
路由守卫与异常页面
本课解决“哪些用户可以进入哪些页面,以及失败后显示什么”的问题。你将实现登录守卫和角色守卫,并用 401、403、404 页面区分未登录、无权限和路由不存在,让页面访问逻辑清晰且可验证。
学习目标
- 使用包装路由实现登录与角色校验
- 正确区分 401、403 和 404 页面
- 保留原访问地址,并在登录后返回目标页面
先区分三类访问失败
未登录表示系统还不知道用户身份,应引导用户登录;已登录但权限不足表示身份已确认,只是不能访问当前资源;路由不存在则表示地址没有匹配到任何页面。
| 场景 | 页面 | 推荐处理 |
|---|---|---|
| 未登录访问受保护页面 | 401 或登录页 | 记录原地址并跳转登录 |
| 已登录但角色不匹配 | 403 | 展示无权限说明和返回入口 |
| 地址没有对应路由 | 404 | 展示未找到页面和首页入口 |
路由守卫只负责前端页面访问体验,不能替代服务端权限校验。即使按钮和页面都被隐藏,后端接口仍必须验证身份与权限。

实现登录守卫与角色守卫
下面的示例用内存状态模拟当前用户。RequireAuth 负责检查登录状态,RequireRole 在已登录的基础上继续检查角色。登录页读取原访问地址,登录成功后再跳回去。
import React, { createContext, useContext, useMemo, useState } from "react";
import {
BrowserRouter,
Link,
Navigate,
Route,
Routes,
useLocation,
useNavigate,
} from "react-router-dom";
import { createRoot } from "react-dom/client";
type Role = "USER" | "ADMIN";
type User = {
name: string;
role: Role;
};
type AuthContextValue = {
user: User | null;
login: (role: Role) => void;
logout: () => void;
};
// 认证上下文只暴露当前用户和登录状态修改方法。
const AuthContext = createContext<AuthContextValue | null>(null);
function useAuth() {
const context = useContext(AuthContext);
if (!context) throw new Error("useAuth 必须在 AuthProvider 内使用");
return context;
}
function AuthProvider({ children }: { children: React.ReactNode }) {
const [user, setUser] = useState<User | null>(null);
const value = useMemo<AuthContextValue>(
() => ({
user,
login: (role) => setUser({ name: "Simon", role }),
logout: () => setUser(null),
}),
[user],
);
return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}
function RequireAuth({ children }: { children: React.ReactNode }) {
const { user } = useAuth();
const location = useLocation();
if (!user) {
// 保存原始 location,登录成功后可恢复路径、查询参数和哈希。
return <Navigate to="/unauthorized" replace state={{ from: location }} />;
}
return <>{children}</>;
}
function RequireRole({
allow,
children,
}: {
allow: Role[];
children: React.ReactNode;
}) {
const { user } = useAuth();
if (!user) {
return <Navigate to="/unauthorized" replace />;
}
// 身份已确认但角色不匹配时进入 403 页面。
if (!allow.includes(user.role)) {
return <Navigate to="/forbidden" replace />;
}
return <>{children}</>;
}
function HomePage() {
const { user, logout } = useAuth();
return (
<main>
<h2>首页</h2>
<p>当前用户:{user ? `${user.name} / ${user.role}` : "未登录"}</p>
<nav>
<Link to="/profile">个人中心</Link>{" "}
<Link to="/admin">管理后台</Link>
</nav>
{user && <button onClick={logout}>退出登录</button>}
</main>
);
}
function LoginPage() {
const { login } = useAuth();
const navigate = useNavigate();
const location = useLocation();
const from = (
location.state as {
from?: { pathname: string; search: string; hash: string };
} | null
)?.from;
const target = from
? `${from.pathname}${from.search}${from.hash}`
: "/";
function handleLogin(role: Role) {
login(role);
navigate(target, { replace: true });
}
return (
<main>
<h2>登录</h2>
<button onClick={() => handleLogin("USER")}>以普通用户登录</button>
<button onClick={() => handleLogin("ADMIN")}>以管理员登录</button>
</main>
);
}
function ProfilePage() {
return <h2>个人中心</h2>;
}
function AdminPage() {
return <h2>管理后台</h2>;
}
function UnauthorizedPage() {
const location = useLocation();
const from = (
location.state as {
from?: { pathname: string; search: string; hash: string };
} | null
)?.from;
return (
<main>
<h2>401 未授权</h2>
<Link to="/login" state={{ from }}>
前往登录
</Link>
</main>
);
}
function ForbiddenPage() {
return (
<main>
<h2>403 无权限</h2>
<Link to="/">返回首页</Link>
</main>
);
}
function NotFoundPage() {
return (
<main>
<h2>404 页面不存在</h2>
<Link to="/">返回首页</Link>
</main>
);
}
function App() {
return (
<AuthProvider>
<BrowserRouter>
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/login" element={<LoginPage />} />
<Route path="/unauthorized" element={<UnauthorizedPage />} />
<Route path="/forbidden" element={<ForbiddenPage />} />
<Route
path="/profile"
element={
<RequireAuth>
<ProfilePage />
</RequireAuth>
}
/>
{/* 先校验登录,再校验角色,职责保持单一。 */}
<Route
path="/admin"
element={
<RequireAuth>
<RequireRole allow={["ADMIN"]}>
<AdminPage />
</RequireRole>
</RequireAuth>
}
/>
<Route path="*" element={<NotFoundPage />} />
</Routes>
</BrowserRouter>
</AuthProvider>
);
}
createRoot(document.getElementById("root")!).render(<App />);预期结果
1. 未登录访问 /profile 或 /admin 时进入 401 页面。
2. 从 401 页面前往登录后,登录成功会返回原目标地址。
3. 以普通用户登录后可进入 /profile;访问 /admin 时进入 403 页面。
4. 以管理员登录后可进入 /admin。
5. 访问不存在的地址时进入 404 页面。示例中的用户状态保存在内存,刷新后会恢复为未登录。真实项目通常通过 Cookie、Token 或会话接口恢复身份,并在恢复完成前显示加载状态,避免页面先跳登录再立即跳回。
为什么要保存原访问地址
用户直接访问 /admin?tab=users 时,守卫不应只记住 /admin。保存完整的 location 可以保留路径、查询参数和哈希,使登录后的返回结果与用户原始意图一致。
返回地址必须来自应用内部路由,不能直接信任外部传入的完整 URL,否则可能形成开放重定向。最稳妥的做法是保存 React Router 的 location 对象,而不是读取任意 redirect 参数后直接跳转。
异步鉴权与加载状态
真实应用常在启动时请求“当前用户”接口。此时鉴权状态至少应区分“检查中、已登录、未登录”,不能把尚未完成的请求直接当成未登录。
片段示例:以下守卫复用上文的 React、Navigate 和 useLocation 导入,并由认证上下文把 status 传入。
type AuthStatus = "loading" | "authenticated" | "anonymous";
function RequireAuth({
status,
children,
}: {
status: AuthStatus;
children: React.ReactNode;
}) {
const location = useLocation();
if (status === "loading") {
return <p>正在验证登录状态...</p>;
}
if (status === "anonymous") {
return <Navigate to="/unauthorized" replace state={{ from: location }} />;
}
return <>{children}</>;
}预期结果
鉴权请求未完成时显示加载提示;确认未登录后才进入 401 页面;确认已登录后渲染受保护页面。这样可以避免刷新页面时出现短暂的错误跳转,也能防止受保护内容在权限结果返回前闪现。
异常页面的设计边界
401 页面应告诉用户需要登录,并提供明确的登录入口。403 页面应说明当前账号没有权限,但不要暴露后台角色规则、资源标识或安全策略细节。404 页面应帮助用户回到首页或常用页面,不应自动猜测并跳转到不确定的地址。
前端守卫用于改善导航体验,真正的数据安全必须由后端接口完成。后端返回 401 时通常清理失效会话并重新登录;返回 403 时保留当前身份,展示无权限提示即可。