TanStack Router 404 与错误处理完全指南:notFound、notFoundComponent、errorComponent 与路由掩码实战

原创2026-09-15 17:10:351,454 阅读
文章标签:前端路由Web框架SSRUI组件

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() 触发重新加载并自动重置边界。

相关源码与测试指引

交叉参考

  • router-core/data-loading:loader 中抛出 notFound() 与错误边界、loader 数据可用性相互影响;errorComponent 重试依赖 router.invalidate()。
  • router-core/type-safety:notFoundComponent 收到的 data 类型为 unknown,使用前必须校验收窄。
登录后查看全文
router