tanstack-router

TanStack Router

为 React 提供类型安全的基于文件的路由，支持路由级数据加载、搜索参数验证、代码拆分和 TanStack Query 集成。

包： @tanstack/react-router | 插件： @tanstack/router-plugin

快速参考

模式	用法
createFileRoute('/path')	定义基于文件的路由
createRootRouteWithContext<T>()	创建带类型化上下文的根路由
createLazyFileRoute('/path')	创建代码拆分的路由组件
zodValidator(schema)	验证搜索参数
Route.useLoaderData()	在组件中访问加载器数据
Route.useParams()	类型安全的路由参数
Route.useSearch()	类型安全的搜索参数
useNavigate()	以编程方式导航
useBlocker()	阻止导航（表单有未保存更改时）
notFound()	从加载器中抛出 404
getRouteApi('/path')	在拆分的文件中使用类型安全的钩子
stripSearchParams(defaults)	从 URL 中清除默认值
retainSearchParams(['key'])	在导航间保留参数
useAwaited({ promise })	暂停执行，直到延迟的 Promise 解析
useCanGoBack()	检查路由器是否可以安全地返回

数据加载

方法	返回值	是否抛出异常	用途
ensureQueryData	数据	是	路由加载器（推荐）
prefetchQuery	void	否	后台预取
fetchQuery	数据	是	需要立即获取数据
defer()（可选）	Promise	否	流式传输非关键数据（自动处理 Promise）

预加载

策略	行为	用途
'intent'	悬停或聚焦时预加载	大多数链接的默认策略
'render'	挂载 Link 时预加载	关键的下一页
'viewport'	Link 进入视口时预加载	首屏以下的内容
false	不预加载	繁重且很少访问的页面

文件组织

文件	用途
__root.tsx	带有 <Outlet /> 的根路由
index.tsx	/ 的索引路由
posts.$postId.tsx	动态参数路由
_authenticated.tsx	无路径布局（身份验证守卫）
dashboard.lazy.tsx	代码拆分组件

常见错误

错误	修复
缺少路由器类型注册	添加包含 Register 接口的 declare module
使用 useParams() 时未传入 from	始终传入 from: '/route/path'，以获取精确类型
普通链接使用 useNavigate()	对 <a> 标签使用 <Link>，以支持无障碍访问和预加载
在加载器中使用 prefetchQuery	使用 ensureQueryData（返回数据，遇到错误时抛出）
在 useEffect 中获取数据	使用路由加载器（避免瀑布式请求）
加载器中的请求按顺序执行	使用 Promise.all 并行发送请求
缺少前导斜杠	始终使用 '/about'，而不是 'about'
TanStackRouterVite 位于 react() 之后	在 Vite 配置中，插件必须放在 react() 之前
strict: false 时参数未解析	使用严格模式，或在导航后手动解析
无路径路由的 notFoundComponent	改为在子路由上定义 notFoundComponent
加载器中止时出现未定义错误	使用 if (!error) return null 为 errorComponent 添加保护
未声明 loaderDeps	声明依赖项，这样加载器只会在依赖项变更时重新运行

委派

• TanStack Query 模式 — 数据获取、缓存、变更：使用 tanstack-query 技能
• TanStack Start — 服务端函数、SSR、服务端身份验证：使用 tanstack-start 技能
• TanStack Table — 使用路由搜索参数渲染表格：使用 tanstack-table 技能
• Router + Query 集成 — 加载器数据流、预加载：参阅 加载器数据流模式

如果有 tanstack-devtools 技能，请委派其处理路由器状态调试和路由树检查。

参考资料

• 设置 — 安装、Vite 配置、文件结构、应用设置、路由器默认选项
• 类型安全 — 注册路由器、from 参数、strict: false、类型工具、getRouteApi
• 数据加载 — 路由加载器、Query 集成、并行加载、流式传输、延迟数据、中止信号、loaderDeps
• 搜索参数 — 验证、剥离/保留中间件、细粒度订阅、防抖、自定义序列化器
• 导航 — Link、活动样式、相对导航、哈希、路由遮罩、阻止器、滚动恢复
• 身份验证和上下文 — beforeLoad、上下文继承、无路径布局、依赖注入、错误处理
• 代码拆分 — 懒加载路由、自动拆分、预加载策略、编程式预加载
• 虚拟文件路由 — rootRoute、route、index、layout、物理构建器、混合使用基于文件和基于代码的路由
• 已知问题 — 20 个已记录问题及其修复方法、反模式
• 加载器 + Query 模式 — 在加载器中使用 ensureQueryData、并行加载、关键与非关键数据、依赖搜索参数的加载器