React 第五十三节 Router中 useRouteError 的使用详解和案例分析

前言

useRouteError 是 React Router v6.4+ 引入的关键错误处理钩子，用于在 路由错误边界（Error Boundary）中获取路由操作过程中发生的错误信息。
它提供了优雅的错误处理机制，让开发者能够创建用户友好的错误界面。

一、useRouteError 核心用途

1.1、错误捕获：

获取路由加载、渲染或数据提交过程中发生的错误

1.2、错误展示：

在错误边界组件中显示有意义的错误信息

1.3、错误恢复：

提供错误恢复机制（如重试按钮）

1.4、错误分类：

根据错误类型显示不同的UI界面

二、useRouteError 基本用法示例

import { useRouteError } from 'react-router-dom';function ErrorPage() {const error = useRouteError();return (<div id="error-page"><h1>哎呀！出错了</h1><p>抱歉，发生了一个意外的错误。</p><p><i>{error.statusText || error.message}</i></p></div>);
}

三、useRouteError 实际应用场景

3.1、基本错误边界组件

import { useRouteError, isRouteErrorResponse } from 'react-router-dom';export function ErrorBoundary() {const error = useRouteError();// 检查是否为路由错误响应if (isRouteErrorResponse(error)) {return (<div className="error-container"><h1 className="error-title">{error.status} {error.statusText}</h1><p className="error-message">{error.data}</p>{error.status === 404 && (<Link to="/" className="home-link">返回首页</Link>)}</div>);}// 处理其他类型的错误return (<div className="error-container"><h1 className="error-title">未知错误</h1><p className="error-message">{error.message || '发生了一个未知错误'}</p><button className="retry-btn"onClick={() => window.location.reload()}>重试</button></div>);
}

3.2、分层错误边界

// 根错误边界 - 应用级别错误
export function RootErrorBoundary() {const error = useRouteError();return (<div className="fullscreen-error"><div className="error-card"><h1>应用错误</h1><p>抱歉，整个应用出现了问题</p><ErrorDetails error={error} /><div className="actions"><button onClick={() => window.location.reload()}>刷新应用</button><a href="/">返回首页</a></div></div></div>);
}// 路由级别错误边界
export function RouteErrorBoundary() {const error = useRouteError();return (<div className="route-error"><h2>页面错误</h2><ErrorDetails error={error} /><div className="actions"><button onClick={() => window.history.back()}>返回上一页</button></div></div>);
}// 错误详情组件
function ErrorDetails({ error }) {return (<div className="error-details"><p><strong>错误信息:</strong> {error.message}</p>{isRouteErrorResponse(error) && (<p><strong>状态码:</strong> {error.status}</p>)}{error.stack && (<details className="stack-trace"><summary>查看技术细节</summary><pre>{error.stack}</pre></details>)}</div>);
}

3.3、在路由配置中使用错误边界

import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import {RootLayout,Dashboard,UserProfile,Settings,RootErrorBoundary,RouteErrorBoundary
} from './components';const router = createBrowserRouter([{path: '/',element: <RootLayout />,errorElement: <RootErrorBoundary />, // 应用级错误边界children: [{index: true,element: <Dashboard />},{path: 'profile/:userId',element: <UserProfile />,errorElement: <RouteErrorBoundary />, // 路由级错误边界loader: userProfileLoader // 可能抛出错误的loader},{path: 'settings',element: <Settings />,errorElement: <RouteErrorBoundary />,action: settingsAction // 可能抛出错误的action}]}
]);function App() {return <RouterProvider router={router} />;
}

3.4、自定义错误类型处理

import { useRouteError } from 'react-router-dom';export function ApiErrorBoundary() {const error = useRouteError();// 处理API错误if (error.name === 'ApiError') {return (<div className="api-error"><h2>API 请求失败</h2><p>错误代码: {error.code}</p><p>{error.message}</p>{error.code === 401 ? (<button onClick={() => location.href = '/login'}>重新登录</button>) : (<button onClick={() => window.location.reload()}>重试</button>)}</div>);}// 处理路由错误响应if (isRouteErrorResponse(error)) {switch (error.status) {case 404:return <NotFoundError error={error} />;case 403:return <ForbiddenError error={error} />;case 500:return <ServerError error={error} />;default:return <GenericHttpError error={error} />;}}// 默认错误处理return <GenericError error={error} />;
}// 404错误组件
function NotFoundError({ error }) {return (<div className="not-found"><h1>页面未找到</h1><p>您访问的页面不存在</p><p>错误信息: {error.data || error.statusText}</p><Link to="/" className="home-link">返回首页</Link></div>);
}// 403错误组件
function ForbiddenError({ error }) {return (<div className="forbidden"><h1>权限不足</h1><p>您没有权限访问此内容</p><div className="actions"><button onClick={() => window.history.back()}>返回上一页</button><Link to="/contact">联系管理员</Link></div></div>);
}

3.5、结合加载器的错误处理

// 用户详情页loader
export async function userLoader({ params }) {try {const user = await fetchUser(params.userId);if (!user) {// 抛出404错误响应throw new Response('用户未找到', {status: 404,statusText: 'Not Found'});}return user;} catch (error) {// 抛出自定义API错误throw new ApiError({message: '加载用户数据失败',code: error.status || 500,originalError: error});}
}// 自定义API错误类
export class ApiError extends Error {constructor({ message, code, originalError }) {super(message);this.name = 'ApiError';this.code = code;this.originalError = originalError;// 保留原始堆栈跟踪if (originalError?.stack) {this.stack = originalError.stack;}}
}

四、useRouteError 高级用法：错误恢复机制

import { useRouteError, useNavigate } from 'react-router-dom';export function RecoverableErrorBoundary() {const error = useRouteError();const navigate = useNavigate();const [retryCount, setRetryCount] = useState(0);const handleRetry = () => {setRetryCount(c => c + 1);navigate('.'); // 重新加载当前路由};const handleBack = () => {navigate(-1); // 返回上一页};return (<div className="recoverable-error"><h1>发生错误</h1><p>{error.message || '请稍后再试'}</p><div className="error-actions"><button onClick={handleRetry} className="retry-btn">重试 {retryCount > 0 && `(${retryCount})`}</button><button onClick={handleBack} className="back-btn">返回</button></div>{retryCount > 2 && (<div className="advanced-options"><p>多次重试失败？</p><button onClick={() => window.location.reload()}>刷新整个页面</button><Link to="/support">联系支持</Link></div>)}</div>);
}

五、useRouteError 错误类型处理指南

错误类型 识别方法 推荐处理方式
404 Not Found： error.status === 404；显示"未找到"页面，提供返回首页链接
403 Forbidden： error.status === 403；显示权限不足信息，提供登录或联系管理员选项
500 Server Error：error.status === 500；显示服务器错误，提供重试或联系支持选项
网络错误 ：error instanceof TypeError；显示连接问题，检查网络并提供重试
自定义错误：自定义错误类；根据业务逻辑定制错误处理
未捕获异常：其他所有错误；显示通用错误信息，提供技术细节

六、useRouteError 最佳实践

6.1、分层错误边界：

应用级：捕获整个应用的意外错误

路由级：处理特定路由的错误

组件级：处理局部UI错误

6.2、用户友好信息：

避免显示技术性错误信息给普通用户

提供清晰的恢复操作指引

为开发环境保留详细错误日志

6.3、错误恢复机制：

提供重试按钮

实现返回上一页功能

添加刷新页面选项

6.4、错误日志记录：

    useEffect(() => {if (error) {logErrorToService(error);}}, [error]);

6.5、开发环境增强：

function ErrorDetails({ error }) {return (<div>{process.env.NODE_ENV === 'development' && (<details><summary>开发人员详情</summary><pre>{error.stack}</pre></details>)}</div>);
}

七、useRouteError 注意事项

7.1、错误边界位置：

错误边界必须位于路由层级中

只能捕获其子组件树中的错误

7.2、错误类型检查：

使用 isRouteErrorResponse 检查路由错误响应

处理各种可能的错误类型

7.3、异步错误处理：

loader/action 中的异步错误会被自动捕获

组件中的错误需要使用 useRouteError 获取

7.4、错误传播：

错误会向上传播到最近的错误边界

未被捕获的错误会导致应用崩溃

7.5、与React错误边界结合：

class ReactErrorBoundary extends React.Component {state = { hasError: false };static getDerivedStateFromError() {return { hasError: true };}render() {if (this.state.hasError) {return <RouterErrorBoundary />;}return this.props.children;}
}