TanStack Router 404 与错误处理完全指南:notFound、notFoundComponent、errorComponent 与路由掩码实战
TanStack Router 404 与错误处理完全指南:notFound、notFoundComponent、errorComponent 与路由掩码实战
导读
本文聚焦 TanStack Router 中"未找到"(Not Found)与错误边界(Error Boundary)两大体系:一类是 URL 路径无法匹配(路由自动处理),另一类是资源缺失(如帖子 ID 不存在,需开发者用 notFound() 手动触发);同时覆盖按路由配置的 errorComponent 错误边界,以及用于弹窗/临时页面场景的路由掩码(Route Masking)机制。读完本文,你将掌握全局/路由级/路由级 404 组件的配置方式、notFoundMode 的 fuzzy/root 差异、错误重试的正确姿势(router.invalidate() 而非 reset()),以及命令式与声明式两种掩码实现方案。
两类"未找到"与一条统一 API
TanStack Router 将 "not found" 划分为两种截然不同的来源,但底层共用同一套 notFound 函数与 notFoundComponent API(见官方指南 not-found-errors.md):
- 路径未匹配(自动):访问的 pathname 不匹配任何已知路由模式,或部分匹配但带有多余路径段。例如访问
/users而路由树中没有该路由,或访问/posts/1/edit而路由树只处理/posts/$postId。这类错误由路由器自动抛出。 - 资源缺失(手动):例如访问
/posts/1时 ID 为 1 的帖子不存在。开发者需要在beforeLoad或loader中使用notFound工具手动抛出。
两者的共同点是都会向上寻找最近的、具备 notFoundComponent 的路由边界来渲染 404 UI。
notFound() 的源码本质
在 not-found.ts 中,notFound 的实现非常轻量:
export function notFound(options: NotFoundError = {}) {
;(options as any).isNotFound = true
if (options.throw) throw options
return options
}
export function isNotFound(obj: any): obj is NotFoundError {
return obj?.isNotFound === true
}
它本质上只是给选项对象打上 isNotFound 标记并返回(或立即抛出)。NotFoundError 支持以下选项:
| 选项 | 类型 | 说明 |
|---|---|---|
routeId |
RouteIds |
指定由哪个路由的边界处理(如 notFound({ routeId: '/_layout' })) |
rootRouteId |
常量 | 等价于 routeId: rootRouteId,强制根路由处理 |
data |
any |
向 notFoundComponent 转发部分数据 |
throw |
boolean |
为 true 时直接抛出而非返回 |
headers |
HeadersInit |
可携带响应头 |
global / _global |
boolean |
已弃用/内部使用,请改用 routeId: rootRouteId |
isNotFound 则被框架内部用于区分"未找到错误"与普通异常——这正是 CatchNotFound 能够只拦截 not-found、放行其他错误的关键。
三层 404 组件配置
1. 全局 404:根路由的 notFoundComponent
在 __root.tsx 上挂载 notFoundComponent 是最常见的全局兜底方案,它作为整个应用的最终边界:
// src/routes/__root.tsx
import { createRootRoute, Outlet, Link } from '@tanstack/react-router'
export const Route = createRootRoute({
component: () => <Outlet />,
notFoundComponent: () => {
return (
<div>
<h1>404 — Page Not Found</h1>
<Link to="/">Go Home</Link>
</div>
)
},
})
2. 路由级默认:defaultNotFoundComponent
若希望"所有有子路由的页面"都自动获得默认 404 UI,可将 defaultNotFoundComponent 传入 createRouter:
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const router = createRouter({
routeTree,
defaultNotFoundComponent: () => {
return (
<div>
<p>Not found!</p>
<Link to="/">Go home</Link>
</div>
)
},
})
注意:defaultNotFoundComponent 只对有子路由的节点生效。官方文档明确解释:叶子节点路由(没有子路由)永远不渲染 <Outlet>,因此没有能力承接 not-found 错误。
该选项在 packages/react-router/src/router.ts 的类型声明中标注默认值为 NotFound,即框架内置的极简 <p>Not Found</p>(实现见 not-found.tsx 的 DefaultGlobalNotFound)。官方文档也直言这个默认组件"刻意保持简陋",强烈建议至少给根路由挂一个 notFoundComponent 或配置 defaultNotFoundComponent。
3. 路由级 404:缺失资源场景
当某个资源不存在时,在 loader(或 beforeLoad)中抛出 notFound(),由该路由或其最近祖先的 notFoundComponent 处理:
// src/routes/posts.$postId.tsx
import { createFileRoute, notFound } from '@tanstack/react-router'
import { getPost } from '../api'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const post = await getPost(postId)
if (!post) throw notFound()
return { post }
},
component: PostComponent,
notFoundComponent: ({ data }) => {
const { postId } = Route.useParams()
return <p>Post "{postId}" not found</p>
},
})
function PostComponent() {
const { post } = Route.useLoaderData()
return <h1>{post.title}</h1>
}
notFound() 的用法与 redirect() 类似——直接 throw 即可中断 loader 执行,其后的代码可安全假定资源存在。也可用 notFound({ throw: true }) 让函数自身抛出。
指定处理边界:routeId 与 rootRouteId
默认情况下,notFound() 由"最近的可处理祖先"接管。若希望强制某个特定父路由处理,传入 routeId:
// src/routes/_layout/posts.$postId.tsx
export const Route = createFileRoute('/_layout/posts.$postId')({
loader: async ({ params: { postId } }) => {
const post = await getPost(postId)
if (!post) throw notFound({ routeId: '/_layout' })
return { post }
},
})
若希望直接打到根路由,使用导出的 rootRouteId 常量(类型上会自动补全合法的路由 ID):
import { createFileRoute, notFound, rootRouteId } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const post = await getPost(postId)
if (!post) throw notFound({ routeId: rootRouteId })
return { post }
},
})
notFoundMode:fuzzy 与 root 的边界归属
当路由匹配失败时,notFoundMode 决定由谁渲染 404。该选项在 router.ts 中声明,默认值为 'fuzzy'。
fuzzy(默认):尽量保留父级布局
路由器会寻找"最近的、有子路由且具备 notFoundComponent(或存在 defaultNotFoundComponent)的匹配祖先"。例如路由树为 __root__ → posts → $postId(三者都配了 notFoundComponent),访问 /posts/1/edit 时渲染:
<Root>
<Posts>
<Post>
<Post.notFoundComponent>
这样能最大限度保留用户预期到达位置附近的布局,提供更多导航上下文。
root:统一交给根路由
const router = createRouter({
routeTree,
notFoundMode: 'root',
})
此时所有路径型 not-found 都直接渲染 <Root.notFoundComponent>,跳过中间的 fuzzy 匹配。
源码佐证:findGlobalNotFoundRouteId
在 router.ts 中,findGlobalNotFoundRouteId 精确实现了上述逻辑:
function findGlobalNotFoundRouteId(
notFoundMode: 'root' | 'fuzzy' | undefined,
routes: ReadonlyArray<AnyRoute>,
) {
if (notFoundMode !== 'root') {
let fallback
for (let i = routes.length - 1; i >= 0; i--) {
const route = routes[i]!
if (route.options.notFoundComponent) {
return route.id
}
fallback ||= route.children && route.id
}
if (fallback) return fallback
}
return rootRouteId
}
可以看到:fuzzy 模式从匹配列表从深到浅扫描,优先返回第一个定义了 notFoundComponent 的路由;若都没有,则回退到"最深的有子路由的节点"(保持向后兼容);root 模式则直接返回 rootRouteId。这套边界归属行为被测试 issue-6351-fuzzy-notfound-layout.test.ts 完整覆盖——该测试断言 fuzzy 404 必须归属到"最深的有子路由且定义了 notFoundComponent 的匹配祖先",否则会错误地跳过 pathless layout 的 notFoundComponent 并退化为 defaultNotFoundComponent。
错误边界:errorComponent
与 not-found 并行的是普通运行时错误。每个路由可配置 errorComponent,它接收 error、info(组件栈)与 reset 三个属性:
// src/routes/posts.$postId.tsx
import { createFileRoute, useRouter } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const res = await fetch(`/api/posts/${postId}`)
if (!res.ok) throw new Error('Failed to load post')
return res.json()
},
component: PostComponent,
errorComponent: PostErrorComponent,
})
function PostErrorComponent({ error }: { error: unknown }) {
const router = useRouter()
return (
<div>
<p>Error: {error instanceof Error ? error.message : String(error)}</p>
<button
onClick={() => {
// Invalidate 会重新执行 loader 并自动重置错误边界
router.invalidate()
}}
>
Retry
</button>
</div>
)
}
function PostComponent() {
const data = Route.useLoaderData()
return <h1>{data.title}</h1>
}
全局默认错误组件
与 defaultNotFoundComponent 对称,createRouter 也支持 defaultErrorComponent(默认值为内置 ErrorComponent,类型声明见 react-router/src/router.ts):
const router = createRouter({
routeTree,
defaultErrorComponent: ({ error }) => {
const router = useRouter()
return (
<div>
<p>
Something went wrong:{' '}
{error instanceof Error ? error.message : String(error)}
</p>
<button onClick={() => router.invalidate()}>Retry</button>
</div>
)
},
})
为什么重试要用 router.invalidate() 而不是 reset()
errorComponent 的 reset 属性只负责清除错误边界内部状态(见 CatchBoundary.tsx 中 reset = () => this.setState({ error: 0 })),它不会重新运行 loader。而 router.invalidate() 会触发全部(或指定)路由的 loader 重新执行,并在数据就绪后自动重置边界。因此针对"loader 抛错"的重试场景,正确姿势始终是 invalidate();若只调用 reset(),页面会立即再次抛错回到错误态。
CatchBoundary 的类组件实现
packages/react-router/src/CatchBoundary.tsx 中,错误边界是一个 React 类组件:
getDerivedStateFromProps依据getResetKey()的变化自动清除错误态(路由切换时自动恢复);getDerivedStateFromError捕获任意抛出的值并包装成[error]数组——包装保证了"任何可抛出的值(包括 falsy)都保持 truthy",从而被状态正确识别;componentDidCatch触发onCatch回调;- 渲染时若处于错误态,则创建
errorComponent(缺省为内置ErrorComponent),并注入error与reset属性。
在组件中抛出 not-found:CatchNotFound
官方推荐在 loader 中抛 not-found(便于类型推导、避免闪烁),但组件内同样可以抛。此时使用 CatchNotFound 组件包裹:
import { CatchNotFound } from '@tanstack/react-router'
function Photo() {
return (
<CatchNotFound
fallback={(error) => <p>Photo not found</p>}
onCatch={(error, errorInfo) => {
// 上报到监控平台
}}
>
<PhotoContent />
</CatchNotFound>
)
}
not-found.tsx 的实现展示了它的关键行为:内部复用一个 CatchBoundary,其 errorComponent 用 isNotFound(error) 判断——只有 not-found 错误才走 fallback,其他错误原样重新抛出交给上层边界。服务端渲染时,reset key 由 pathname + status 计算,保证 SSR 与客户端行为一致。
notFoundComponent 中的数据限制
notFoundComponent 中不能可靠使用 useLoaderData——loader 可能尚未完成或根本没有执行。安全的 hooks 是 useParams、useSearch、useRouteContext:
notFoundComponent: ({ data }) => {
// SAFE — always available:
const params = Route.useParams()
const search = Route.useSearch()
const context = Route.useRouteContext()
// UNSAFE — may be undefined:
// const loaderData = Route.useLoaderData()
return <p>Item {params.id} not found</p>
}
通过 data 选项转发部分数据
若需要在 404 UI 中展示部分加载结果,可通过 notFound() 的 data 选项转发,并在组件内做类型收窄:
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const partialData = await getPartialData(params.id)
if (!partialData.fullResource) {
throw notFound({ data: { name: partialData.name } })
}
return partialData
},
notFoundComponent: ({ data }) => {
// data 的类型是 unknown,需要自行校验
const info = data as { name: string } | undefined
return <p>{info?.name ?? 'Resource'} not found</p>
},
})
路由掩码(Route Masking):URL 与真实路由分离
路由掩码让地址栏显示的 URL 与实际渲染的路由不一致,典型场景是弹窗:导航到 /photo/5/modal,但地址栏显示 /photos/5;或导航到带 ?showLogin=true 的页面但掩掉 search 参数。
原理:location.state.__tempLocation
掩码数据存储在历史条目的 location.state 中。当路由器从 history 解析 location 时,若发现 __tempLocation 属性,就会用其中的运行时 location 替代 URL 解析出的 location;同时把历史 location 保存到 maskedLocation,供 Devtools 等识别"当前 URL 被掩码了"。关键推论:掩码数据一旦脱离本地历史栈(复制、分享、新标签页打开)就会丢失,浏览器会直接访问可见的(被掩码的)URL——这恰恰是掩码的目的。
命令式掩码:<Link> 与 useNavigate
mask 选项接受与 Link/navigate() 相同的导航对象(to、params、search、replace、state 等),且完全类型安全:
import { Link } from '@tanstack/react-router'
function PhotoGrid({ photoId }: { photoId: string }) {
return (
<Link
to="/photos/$photoId/modal"
params={{ photoId }}
mask={{
to: '/photos/$photoId',
params: { photoId },
}}
>
Open Photo
</Link>
)
}
import { useNavigate } from '@tanstack/react-router'
function OpenPhotoButton({ photoId }: { photoId: string }) {
const navigate = useNavigate()
return (
<button
onClick={() =>
navigate({
to: '/photos/$photoId/modal',
params: { photoId },
mask: {
to: '/photos/$photoId',
params: { photoId },
},
})
}
>
Open Photo
</button>
)
}
声明式掩码:createRouteMask
若同一掩码规则在多处复用,可以注册到路由器的 routeMasks 选项,避免在每一个 <Link> 上重复书写:
import { createRouter, createRouteMask } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const photoModalMask = createRouteMask({
routeTree,
from: '/photos/$photoId/modal',
to: '/photos/$photoId',
params: (prev) => ({ photoId: prev.photoId }),
})
const router = createRouter({
routeTree,
routeMasks: [photoModalMask],
})
createRouteMask 必须提供 routeTree、from(被掩码的路由 ID)以及标准导航选项(to、search、params、replace 等);params 可以是函数,接收上一个参数并返回新参数,同样类型安全。
unmaskOnReload:刷新时是否解开掩码
默认情况下,本地刷新页面时 URL 保持掩码状态(因为历史栈仍在内存中)。若希望刷新后回到真实 URL,有三个层级(优先级从低到高):
// 1. 路由器级默认
const router = createRouter({
routeTree,
unmaskOnReload: true,
})
// 2. 单条 route mask
const mask = createRouteMask({
routeTree,
from: '/photos/$photoId/modal',
to: '/photos/$photoId',
params: (prev) => ({ photoId: prev.photoId }),
unmaskOnReload: true,
})
// 3. 单次导航(优先级最高)
<Link
to="/photos/$photoId/modal"
params={{ photoId }}
mask={{ to: '/photos/$photoId', params: { photoId } }}
unmaskOnReload
>
Open Photo
</Link>
在 router.ts 中可以看到,nextHistory.unmaskOnReload ?? this.options.unmaskOnReload ?? false 正是按"导航级 → 路由器级 → 默认 false"的优先级解析;BuildNextOptions.mask 也声明了 unmaskOnReload 字段(见 router.ts)。
常见错误清单(务必规避)
1. HIGH:还在用已弃用的 NotFoundRoute
// WRONG — NotFoundRoute 会阻止 notFound() 和 notFoundComponent 生效
import { NotFoundRoute } from '@tanstack/react-router'
const notFoundRoute = new NotFoundRoute({ component: () => <p>404</p> })
const router = createRouter({ routeTree, notFoundRoute })
// CORRECT — 在根路由上使用 notFoundComponent
export const Route = createRootRoute({
component: () => <Outlet />,
notFoundComponent: () => <p>404</p>,
})
NotFoundRoute 是路由而非组件:它依赖父路由的 <Outlet> 才能渲染,无法使用布局,且路径匹配是"宽松"的(/post/1/2/3 会匹配 NotFoundRoute)。而 notFoundComponent 可挂载到任意路由、兼容布局,且路径匹配严格(/post/1/2/3 对 $postId 是多余的路径段,会触发 not-found)。迁移只需两步:从 createRouter 移除 notFoundRoute,给根路由(或其他路由)加上 notFoundComponent。源码中 router.ts 会对仍使用 notFoundRoute 的配置打印弃用警告。注意:notFoundComponent 不支持渲染 <Outlet>。
2. MEDIUM:在 notFoundComponent 中读取 useLoaderData
loader 可能没执行完,数据为 undefined。改用 useParams / useSearch / useRouteContext,或通过 notFound({ data }) 显式转发。
3. MEDIUM:指望叶子路由捕获路径型 404
只有有子路由(渲染 <Outlet>)的路由才能承接路径不匹配的 404。/posts/$postId 这样的叶子路由上的 notFoundComponent 只对"本路由 loader 中抛出的 notFound()"生效,未匹配的子路径会冒泡到最近的父级边界。
4. MEDIUM:以为掩码 URL 能跨分享存活
掩码数据在 location.state 中,复制/分享/新标签页打开后即丢失,浏览器会直接导航到可见 URL。
5. HIGH(跨技能):只用 reset() 重试 loader 错误
reset() 只清错误态不重跑 loader;应使用 router.invalidate() 触发重新加载并自动重置边界。
相关源码与测试指引
notFound/isNotFound实现:packages/router-core/src/not-found.tsnotFoundMode与findGlobalNotFoundRouteId:packages/router-core/src/router.tsCatchBoundary/ErrorComponent:packages/react-router/src/CatchBoundary.tsxCatchNotFound/DefaultGlobalNotFound:packages/react-router/src/not-found.tsxdefaultErrorComponent/defaultNotFoundComponent类型声明:packages/react-router/src/router.ts- fuzzy 404 边界归属测试:packages/router-core/tests/issue-6351-fuzzy-notfound-layout.test.ts
- loader 中
notFound()根边界测试:packages/router-core/tests/issue-4078-loader-notfound-root-boundary.test.ts - SSR 场景 not-found 测试:packages/router-core/tests/server-serial-ssr-notfound.test.ts
- 官方指南:docs/router/guide/not-found-errors.md 与 docs/router/guide/route-masking.md
交叉参考
- router-core/data-loading:loader 中抛出
notFound()与错误边界、loader 数据可用性相互影响;errorComponent重试依赖router.invalidate()。 - router-core/type-safety:
notFoundComponent收到的data类型为unknown,使用前必须校验收窄。