执行契约
- 适用场景
- 一个路由的 Loader 或渲染失败应被局部隔离并提供恢复动作。
- 不要使用
- 不要用通用 errorComponent 表示预期的 404 或重定向。
- 前置检查
- 区分 not found、redirect、可重试错误和未知异常，并确定最近的恢复边界。
- 验证结果
- 逐一触发 Loader 和组件错误，确认兄弟路由可用、重试会重置状态、未知错误仍可观测。
- 失败模式
- 重试后仍显示旧错误通常表示只重新执行请求而未重置 Router 错误状态。
- 安全边界
- 面向用户的错误不得泄漏堆栈、秘密、数据库信息或内部响应体。
行为契约
Loader、beforeLoad 或组件抛出的普通错误由最近的 route errorComponent 捕获。notFound 与 redirect 有各自控制流，不应当转换成普通 Error。
路由级恢复
reset 重置错误边界。展示稳定、面向用户的文案，并让内部错误进入日志系统。除非这是受控开发工具，不要直接渲染 error.stack。
import type { ErrorComponentProps } from '@tanstack/react-router'
function IssuesError({ reset }: ErrorComponentProps) {
return (
<section role="alert">
<h1>Unable to load issues.</h1>
<button type="button" onClick={reset}>Retry</button>
</section>
)
}
export const Route = createFileRoute('/issues/')({
loader: loadIssues,
errorComponent: IssuesError,
component: IssuesPage,
})全局兜底
在 createRouter 配置 defaultErrorComponent，覆盖没有局部边界的路由。错误边界不是监控：生产环境仍需记录异常、路由位置与请求关联信息。