tanstack-vue-router

TanStack Vue Router（@tanstack/vue-router）是 TanStack Router 的 Vue 绑定。本技能构建在 router-core 之上，建议先阅读 router-core 了解基础概念；它专门覆盖 Vue 相关的绑定、组件、组合式函数与搭建流程。

核心注意点

• TanStack Router 类型完全推断，不要强制类型转换，也不要为推断出的值添加注解。
• TanStack Router 是客户端优先，默认情况下加载器（loader）在客户端而非服务端运行。
• 大多数组合式函数返回 Ref<T>：脚本中通过 .value 访问，模板中自动解包，这是与 React 版本最大的区别。
• 不要将 @tanstack/vue-router 与 vue-router（官方 Vue 路由）混淆，它们是两个完全不同的库，API 不同。

完整搭建：基于 Vite 的文件路由

1. 安装依赖：npm install @tanstack/vue-router；npm install -D @tanstack/router-plugin @vitejs/plugin-vue-jsx。
2. 配置 Vite 插件（vite.config.ts）：引入 vite、@vitejs/plugin-vue、@vitejs/plugin-vue-jsx 及 @tanstack/router-plugin/vite 的 tanstackRouter；插件顺序中 tanstackRouter 必须先于 vue()，配置 target: 'vue' 与 autoCodeSplitting: true，并加入 vue() 和 vueJsx()（JSX/TSX 路由文件必需）。
3. 创建根路由（src/routes/__root.tsx）：从 @tanstack/vue-router 引入 createRootRoute、Link、Outlet，导出 Route = createRootRoute({ component: RootLayout })，在 RootLayout 中使用 Link 与 Outlet。
4. 创建路由文件（src/routes/index.tsx）：引入 createFileRoute，导出 Route = createFileRoute('/')({ component: HomePage })。
5. 创建路由实例并注册类型（src/main.tsx）：引入 createApp、RouterProvider、createRouter 与 routeTree.gen 的 routeTree；const router = createRouter({ routeTree })；通过 declare module '@tanstack/vue-router' 注册 router 类型（必需，否则 Link/useNavigate/useSearch 没有类型安全）；createApp(RouterProvider, { router }).mount('#root')。

组合式函数参考（均从 @tanstack/vue-router 引入，多数返回 Ref<T>）

• useRouter()：返回 TRouter，不是 Ref。
• useRouterState()：返回 Ref<T>，订阅路由状态变化，暴露整个状态因此有性能成本；对 matches 或 location 建议用 useMatches 与 useLocation。
• useNavigate()：返回函数，不是 Ref。
• useSearch({ from })：返回 Ref<T>。
• useParams({ from })：返回 Ref<T>。
• useLoaderData({ from })：返回 Ref<T>。
• useMatch({ from })：返回 Ref<T>。
• 其他：useMatches() 返回 Ref<Array<Match>>；useRouteContext({ from }) 返回 Ref<T>；useBlocker({ shouldBlockFn }) 阻止导航（用于未保存更改）；useCanGoBack() 返回 Ref<boolean>；useLocation() 返回 Ref<ParsedLocation>；useLoaderDeps({ from }) 返回 Ref<T>；useLinkProps() 返回 LinkHTMLAttributes；useMatchRoute() 返回函数，调用后返回 Ref<false | Params>。

组件参考

• RouterProvider：在 createApp 或模板中使用，<RouterProvider :router="router" />。
• Link：类型安全的导航链接，支持作用域插槽获取激活状态（isActive）。
• Outlet：渲染匹配的子路由组件。
• Navigate：声明式重定向（在 onMounted 中触发导航）。
• Await：用于延迟数据的异步 setup 组件，配合 Vue 的 <Suspense> 使用。
• CatchBoundary：使用 Vue 的 onErrorCaptured 的错误边界。
• Html 与 Body：Vue 专属的 SSR 外壳组件。
• ClientOnly：仅在 onMounted（水合完成）后渲染子节点，可提供 fallback。

Vue 专属模式

• 通过 createLink 创建自定义 Link 组件：使用 defineComponent 与 h()，再用 createLink 包装。
• 渲染函数：@tanstack/vue-router 内部所有组件都使用 h() 渲染函数；路由组件可用 SFC 模板或渲染函数。
• 使用路由上下文做鉴权：createRootRouteWithContext<{ auth: AuthState }>()，createRouter 传入 context，在 beforeLoad 中通过 context 检查并 redirect 到登录页。
• 代码分割的 Vue 文件约定（配合 autoCodeSplitting，可选，不是必需）：myRoute.ts 路由配置、myRoute.component.vue 路由组件（懒加载）、myRoute.errorComponent.vue 错误组件（懒加载）、myRoute.notFoundComponent.vue 未找到组件（懒加载）、myRoute.lazy.ts 懒加载路由选项。

常见错误

1. 关键：脚本块中忘记 .value。组合式函数返回 Ref<T>，脚本中用 .value 访问，模板自动解包。
2. 高：与官方 vue-router 混淆。不要使用 vue-router 的 <router-view>、<router-link>、useRoute()、useRouter()；应使用 @tanstack/vue-router 的导入。
3. 高：在 beforeLoad 或 loader 中使用 Vue hooks。它们不是组件 setup 函数，而是普通异步函数，不能使用 Vue 组合式函数，应通过路由上下文传递状态。
4. 中：插件 target 设置错误。必须在路由插件配置中设置 target: 'vue'，默认是 'react'。

交叉引用：../tanstack-router-core/SKILL.md 包含面向特定领域模式（搜索参数、数据加载、导航、鉴权、SSR 等）的所有子技能。