React 路由守衛

下面，我們來系統的梳理關于 React Router 路由守衛 的基本知識點：

一、路由守衛概述

1.1 什么是路由守衛

路由守衛是一種在用戶導航到特定路由之前或離開特定路由時執行邏輯的機制。它允許開發者控制用戶訪問權限、驗證條件或執行數據預加載等操作。

1.2 為什么需要路由守衛

訪問控制：限制未授權用戶訪問敏感頁面
數據預加載：在路由渲染前獲取必要數據
表單保護：防止用戶意外離開包含未保存數據的頁面
權限驗證：根據用戶角色顯示不同內容
SEO優化：確保頁面渲染前滿足SEO要求

二、核心守衛類型

2.1 進入守衛（Before Enter）

在路由渲染前執行的守衛邏輯：

// 使用自定義守衛組件
function AuthGuard({ children }) {const { isAuthenticated } = useAuth();const navigate = useNavigate();const location = useLocation();useEffect(() => {if (!isAuthenticated) {navigate('/login', {state: { from: location },replace: true});}}, [isAuthenticated, navigate, location]);return isAuthenticated ? children : <LoadingSpinner />;
}// 在路由配置中使用
<Route path="/dashboard" element={<AuthGuard><Dashboard /></AuthGuard>}
/>

2.2 離開守衛（Before Leave）

在用戶離開當前路由前執行的守衛邏輯：

function UnsavedChangesGuard() {const { isDirty } = useForm();const navigate = useNavigate();useEffect(() => {const handleBeforeUnload = (e) => {if (isDirty) {e.preventDefault();e.returnValue = '';}};window.addEventListener('beforeunload', handleBeforeUnload);return () => {window.removeEventListener('beforeunload', handleBeforeUnload);};}, [isDirty]);useBlocker((tx) => {if (isDirty && !window.confirm('您有未保存的更改，確定要離開嗎？')) {tx.retry();}}, isDirty);return null;
}// 在需要保護的組件中使用
function EditProfile() {return (<><UnsavedChangesGuard />{/* 表單內容 */}</>);
}

2.3 數據加載守衛（Data Loading）

在路由渲染前加載必要數據：

function DataLoader({ children, loader }) {const [data, setData] = useState(null);const [loading, setLoading] = useState(true);const [error, setError] = useState(null);const navigate = useNavigate();useEffect(() => {const fetchData = async () => {try {const result = await loader();setData(result);} catch (err) {setError(err);navigate('/error', { state: { error: err.message } });} finally {setLoading(false);}};fetchData();}, [loader, navigate]);if (loading) return <LoadingSpinner />;if (error) return null; // 已重定向到錯誤頁return children(data);
}// 使用示例
<Route path="/user/:id" element={<DataLoader loader={() => fetchUser(userId)}>{(user) => <UserProfile user={user} />}</DataLoader>}
/>

三、實現路由守衛的四種模式

3.1 高階組件模式（HOC）

function withGuard(Component, guard) {return function GuardedComponent(props) {const navigate = useNavigate();const location = useLocation();useEffect(() => {const result = guard({ location, navigate });if (result?.redirect) {navigate(result.redirect, {replace: true,state: { from: location }});}}, [navigate, location]);return <Component {...props} />;};
}// 定義守衛函數
const authGuard = ({ location }) => {const { isAuthenticated } = useAuth();return !isAuthenticated ? { redirect: `/login?from=${location.pathname}` } : null;
};// 應用守衛
const GuardedDashboard = withGuard(Dashboard, authGuard);

3.2 路由包裝器模式

function RouteGuard({ children, conditions }) {const navigate = useNavigate();const location = useLocation();useEffect(() => {for (const condition of conditions) {const result = condition({ location, navigate });if (result?.redirect) {navigate(result.redirect, {replace: true,state: { from: location }});return;}}}, [conditions, navigate, location]);return children;
}// 使用示例
<Route path="/admin" element={<RouteGuard conditions={[authGuard, adminGuard]}><AdminPanel /></RouteGuard>}
/>

3.3 React Router v6.4+ Loader 模式

const router = createBrowserRouter([{path: '/dashboard',element: <Dashboard />,loader: async () => {const isAuthenticated = await checkAuth();if (!isAuthenticated) {throw redirect('/login');}const data = await fetchDashboardData();return data;},errorElement: <ErrorPage />}
]);// 在組件中使用加載的數據
function Dashboard() {const data = useLoaderData();// 渲染數據...
}

3.4 路由配置元數據模式

const routes = [{path: '/',element: <Home />,public: true},{path: '/profile',element: <Profile />,guards: [authGuard]},{path: '/admin',element: <Admin />,guards: [authGuard, adminGuard]}
];function GuardedRoutes() {return (<Routes>{routes.map((route) => (<Routekey={route.path}path={route.path}element={<GuardProvider guards={route.guards || []}>{route.element}</GuardProvider>}/>))}</Routes>);
}function GuardProvider({ children, guards }) {const navigate = useNavigate();const location = useLocation();useEffect(() => {for (const guard of guards) {const result = guard({ location, navigate });if (result?.redirect) {navigate(result.redirect, {replace: true,state: { from: location }});return;}}}, [guards, navigate, location]);return children;
}

四、常見守衛場景實現

4.1 認證守衛

function useAuthGuard(options = {}) {const { loginPath = '/login' } = options;const { isAuthenticated, isLoading } = useAuth();const navigate = useNavigate();const location = useLocation();useEffect(() => {if (!isLoading && !isAuthenticated) {navigate(loginPath, {replace: true,state: { from: location }});}}, [isAuthenticated, isLoading, navigate, location, loginPath]);return { isAuthenticated, isLoading };
}// 使用示例
function AuthGuard({ children }) {const { isLoading } = useAuthGuard();if (isLoading) return <LoadingSpinner />;return children;
}

4.2 角色權限守衛

function RoleGuard({ children, requiredRoles }) {const { user } = useAuth();const navigate = useNavigate();const location = useLocation();useEffect(() => {if (user && !hasRequiredRoles(user.roles, requiredRoles)) {navigate('/forbidden', {replace: true,state: { from: location }});}}, [user, requiredRoles, navigate, location]);if (!user) return <LoadingSpinner />;return hasRequiredRoles(user.roles, requiredRoles) ? children : null;
}// 輔助函數
function hasRequiredRoles(userRoles, requiredRoles) {return requiredRoles.some(role => userRoles.includes(role));
}// 使用示例
<Route path="/admin" element={<RoleGuard requiredRoles={['admin', 'superadmin']}><AdminPanel /></RoleGuard>}
/>

4.3 訂閱狀態守衛

function SubscriptionGuard({ children }) {const { subscription } = useUser();const navigate = useNavigate();useEffect(() => {if (subscription?.status === 'expired') {navigate('/renew-subscription', { replace: true });} else if (!subscription?.isActive) {navigate('/pricing', { replace: true });}}, [subscription, navigate]);return subscription?.isActive ? children : <LoadingSpinner />;
}

4.4 功能開關守衛

function FeatureGuard({ children, feature }) {const { isFeatureEnabled } = useFeatureFlags();const navigate = useNavigate();useEffect(() => {if (!isFeatureEnabled(feature)) {navigate('/feature-disabled', { replace: true });}}, [feature, isFeatureEnabled, navigate]);return isFeatureEnabled(feature) ? children : null;
}

五、高級守衛模式

5.1 組合守衛

function composeGuards(...guards) {return function CombinedGuard({ location, navigate }) {for (const guard of guards) {const result = guard({ location, navigate });if (result) return result;}return null;};
}// 創建組合守衛
const adminAreaGuard = composeGuards(authGuard,adminGuard,subscriptionGuard
);// 使用組合守衛
<Route path="/admin" element={<RouteGuard guard={adminAreaGuard}><AdminPanel /></RouteGuard>}
/>

5.2 異步守衛

function AsyncGuard({ children, guard }) {const [isAllowed, setIsAllowed] = useState(null);const navigate = useNavigate();const location = useLocation();useEffect(() => {let isMounted = true;const checkGuard = async () => {try {const result = await guard({ location, navigate });if (isMounted) {if (result?.redirect) {navigate(result.redirect, {replace: true,state: { from: location }});} else {setIsAllowed(true);}}} catch (error) {if (isMounted) {navigate('/error', {state: { error: error.message },replace: true});}}};checkGuard();return () => {isMounted = false;};}, [guard, navigate, location]);if (isAllowed === null) return <LoadingSpinner />;return isAllowed ? children : null;
}// 使用示例
const asyncAuthGuard = async () => {const isAuth = await checkAuthToken();return isAuth ? null : { redirect: '/login' };
};<Route path="/dashboard" element={<AsyncGuard guard={asyncAuthGuard}><Dashboard /></AsyncGuard>}
/>

5.3 條件重定向守衛

function ConditionalRedirect({ children, condition, to }) {const navigate = useNavigate();const location = useLocation();useEffect(() => {if (condition()) {navigate(to, {replace: true,state: { from: location }});}}, [condition, to, navigate, location]);return condition() ? null : children;
}// 使用示例
<Route path="/profile" element={<ConditionalRedirect condition={() => isMobile()} to="/mobile/profile"><DesktopProfile /></ConditionalRedirect>}
/>

六、實踐與常見問題

6.1 路由守衛最佳實踐

守衛順序：先認證后權限，先通用后特殊
加載狀態：異步檢查時提供加載指示器
錯誤處理：妥善處理守衛中的錯誤
避免循環：確保守衛邏輯不會導致無限重定向
測試覆蓋：為守衛編寫單元測試和集成測試

6.2 常見問題解決方案

問題：無限重定向循環

// 登錄頁面守衛
function LoginPage() {const { isAuthenticated } = useAuth();const navigate = useNavigate();const location = useLocation();useEffect(() => {if (isAuthenticated) {// 檢查來源是否已經是登錄頁const from = location.state?.from?.pathname || '/';if (from !== '/login') {navigate(from, { replace: true });} else {navigate('/', { replace: true });}}}, [isAuthenticated, navigate, location]);// 渲染登錄表單...
}

問題：守衛多次觸發

function StableGuard({ children, guard }) {const navigate = useNavigate();const location = useLocation();const initialCheck = useRef(false);useEffect(() => {if (!initialCheck.current) {initialCheck.current = true;const result = guard({ location, navigate });if (result?.redirect) {navigate(result.redirect, {replace: true,state: { from: location }});}}}, [guard, navigate, location]);return children;
}

問題：組件卸載時導航

function SafeEffectGuard({ children, guard }) {const navigate = useNavigate();const location = useLocation();const isMounted = useRef(true);useEffect(() => {return () => {isMounted.current = false;};}, []);useEffect(() => {const result = guard({ location, navigate });if (result?.redirect && isMounted.current) {navigate(result.redirect, {replace: true,state: { from: location }});}}, [guard, navigate, location]);return children;
}

七、案例：電商平臺路由守衛

// 路由配置
const router = createBrowserRouter([{path: '/',element: <MainLayout />,children: [{index: true,element: <HomePage />},{path: 'product/:id',element: <ProductDetailPage />,loader: async ({ params }) => {const product = await fetchProduct(params.id);if (!product) throw new Error('Product not found');return product;},errorElement: <ProductErrorPage />},{path: 'cart',element: <CartPage />,guards: [authGuard]},{path: 'checkout',element: <CheckoutPage />,guards: [authGuard, cartNotEmptyGuard],loader: async () => {const [cart, addresses] = await Promise.all([fetchCart(),fetchAddresses()]);return { cart, addresses };}},{path: 'admin',element: <AdminLayout />,guards: [authGuard, adminGuard],children: [{index: true,element: <AdminDashboard />},{path: 'products',element: <ProductManagement />}]}]},{path: '/login',element: <LoginPage />},{path: '*',element: <NotFoundPage />}
]);// 購物車非空守衛
const cartNotEmptyGuard = ({ navigate }) => {const { cartItems } = useCart();if (cartItems.length === 0) {navigate('/cart', {state: { message: '請先添加商品到購物車' },replace: true});return { block: true };}return null;
};// 管理員守衛
const adminGuard = ({ navigate }) => {const { user } = useAuth();if (!user?.roles.includes('admin')) {navigate('/forbidden', { replace: true });return { block: true };}return null;
};