TanStack Router 是面向 React 单页应用（SPA）的类型安全、基于文件的路由方案，支持路由级数据加载，并可与 TanStack Query 集成。文档标注的版本为 @tanstack/react-router@1.146.2，最后更新于 2026-01-09。
一、用途 用于构建 React SPA 的路由层：以文件约定定义路由，自动生成路由树，从而获得类型安全的导航、参数与搜索参数，并在渲染前完成数据加载。
二、安装 npm install @tanstack/react-router @tanstack/router-devtools npm install -D @tanstack/router-plugin 可选（Zod 校验适配器）： npm install @tanstack/zod-adapter zod
三、主要能力
- 类型安全导航：<Link to="/posts/$postId" params={{ postId: '123' }} />，路由可自动补全，参数有类型；非法路由会触发 TypeScript 报错。
- 路由 Loader：在渲染前获取数据，组件内通过 useLoaderData 获得完整类型的数据。
- TanStack Query 集成：在 loader 中通过 queryClient.ensureQueryData 预取并缓存，组件内用 useQuery 读取。
- 虚拟文件路由（v1.140+）：当文件约定不适用时，可用 @tanstack/virtual-file-routes 以编程方式配置路由，并可与文件路由混用（physical）。
- 搜索参数校验：支持内联校验，也推荐使用 @tanstack/zod-adapter 的 zodValidator 与 fallback。文档建议用 .catch() 静默修正错误参数，用 .default() 配合 errorComponent 展示校验错误。
- 错误边界：支持路由级 errorComponent（含 error、reset）与全局 defaultErrorComponent，以及 notFoundComponent。
- 鉴权：通过 beforeLoad 在加载前保护路由，未通过时 throw redirect 跳转登录，并可通过 RouterProvider 的 context 传入鉴权状态；也可用无路径布局路由保护多个子路由。
四、使用方式 Vite 配置中 TanStackRouterVite 必须位于 react() 之前（顺序很重要）。文件结构示例：src/routes/ 下 __root.tsx 使用 createRootRoute() 与 <Outlet />，index.tsx 使用 createFileRoute('/')，posts.$postId.tsx 使用 createFileRoute('/posts/$postId')。应用入口从 ./routeTree.gen 导入自动生成的 routeTree，用 createRouter 创建路由并渲染 <RouterProvider router={router} />。虚拟路由需在 Vite 配置中设置 target: 'react' 与 virtualRouteConfig 指向 routes.ts。
五、适用场景 需要类型安全路由与参数、路由级数据预取、搜索参数校验、路由级鉴权与错误处理的 React SPA；需要自定义路由组织、混合文件与代码路由、复杂嵌套布局的项目。
六、已知问题与限制（文档列出 20 项，含规避方法） 包括：devtools 依赖解析需安装 @tanstack/router-devtools；Vite 插件顺序错误导致路由不生成；缺少类型注册导致 Link 无类型；loader 未运行；TanStack Form 内存泄漏（已在最新版本修复）；虚拟路由 index/layout 冲突；搜索参数类型推断问题（建议改用 @tanstack/zod-adapter 的 zodValidator）；TanStack Start 重载时 validateSearch 失效；服务端函数校验错误结构丢失需手动解析；useParams({ strict: false }) 返回未解析值；无路径路由 notFoundComponent 不渲染；快速导航中断 loader 时 errorComponent 收到 undefined 错误；Vitest 下 useState 为 null（临时可注释 tanstackStart()）；流式 SSR loader 抛错导致开发服务器崩溃（应始终 await 或 catch）；预渲染 filter 返回零结果时构建挂起；Docker 中预渲染失败（可设置 preview.host: true）；head() 早于 loader 完成导致元数据不完整；虚拟路由不支持手动懒加载（应使用自动代码分割）。部分问题官方状态为已知问题、需规避或修复 PR 进行中。
七、暂未提供 文档未提供收费、价格、平台支持范围、性能基准或效果数据等信息。