---
id: router.route-error-boundary
kind: error
product: router
framework: react
locale: zh-CN
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "^1"
verifiedAgainst: "@tanstack/react-router@1.170.18"
contentModel: 2
packages:
  - "@tanstack/react-router"
tasks:
  - "handle-loader-error"
  - "route-error-component"
  - "retry-route"
sourceRefs:
  - "https://tanstack.com/start/latest/docs/framework/react/guide/error-boundaries"
---

# 隔离路由 Loader 与渲染错误

> 为全局 Router 设置默认错误组件，并在需要独立恢复的路由上覆盖 errorComponent。

## 执行契约

- **适用场景:** 一个路由的 Loader 或渲染失败应被局部隔离并提供恢复动作。
- **不要使用:** 不要用通用 errorComponent 表示预期的 404 或重定向。
- **前置检查:** 区分 not found、redirect、可重试错误和未知异常，并确定最近的恢复边界。
- **验证结果:** 逐一触发 Loader 和组件错误，确认兄弟路由可用、重试会重置状态、未知错误仍可观测。
- **失败模式:** 重试后仍显示旧错误通常表示只重新执行请求而未重置 Router 错误状态。
- **安全边界:** 面向用户的错误不得泄漏堆栈、秘密、数据库信息或内部响应体。

## 行为契约

Loader、beforeLoad 或组件抛出的普通错误由最近的 route errorComponent 捕获。notFound 与 redirect 有各自控制流，不应当转换成普通 Error。

## 路由级恢复

reset 重置错误边界。展示稳定、面向用户的文案，并让内部错误进入日志系统。除非这是受控开发工具，不要直接渲染 error.stack。

File: `src/routes/issues/index.tsx`

```tsx
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，覆盖没有局部边界的路由。错误边界不是监控：生产环境仍需记录异常、路由位置与请求关联信息。

## Official sources

- https://tanstack.com/start/latest/docs/framework/react/guide/error-boundaries