# TanStack 路由器指南 (React) TanStack Router 是一个完全类型安全、基于文件的 React 路由器。它提供一流的搜索参数 API、带有 SWR 缓存的内置数据加载、自动代码分割和 100% 推断的 TypeScript 类型。专为客户优先的 SPA 设计，具有可选的 SSR 支持。 ## 安装 npm 安装@tanstack/react-router npm install -D @tanstack/路由器插件 # 可选：开发工具 npm install @tanstack/react-router-devtools ## Vite快速入门（推荐） **1\.配置Vite：** // vite.config.ts 从“vite”导入{defineConfig} 从“@vitejs/plugin-react”导入反应从 '@tanstack/router-plugin/vite' 导入 { tanstackRouter } 导出默认的defineConfig({ 插件：[ tanstackRouter({ 目标: 'react', autoCodeSplitting: true }), React(), // 必须在 tanstackRouter 之后 ], }) **2\.创建根路由：** // src/routes/__root.tsx 从 '@tanstack/react-router' 导入 { createRootRoute, Link, Outlet } 从 '@tanstack/react-router-devtools' 导入 { TanStackRouterDevtools } 导出常量路由 = createRootRoute({ 组件：() => ( <> <导航> 首页关于 <出口/> ), }) **3\.创建路线：** // src/routes/index.tsx 从 '@tanstack/react-router' 导入 { createFileRoute } 导出 const 路由 = createFileRoute('/')({ 组件：() =>

欢迎回家！

, }) // src/routes/about.tsx 导出 const 路由 = createFileRoute('/about')({ 组件：() =>

关于页面

, }) **4\.安装路由器：** // src/main.tsx 从 'react' 导入 { StrictMode } 从'react-dom/client'导入ReactDOM 从 '@tanstack/react-router' 导入 { RouterProvider, createRouter } 从'./routeTree.gen'导入{routeTree} const 路由器 = createRouter({ 路由树 }) // 全局注册路由器类型以保证类型安全声明模块'@tanstack/react-router'{ 接口寄存器{ 路由器：路由器类型 } } ReactDOM.createRoot(document.getElementById('root')!).render( <严格模式> ，） ## 基于文件的路由（命名约定）路由位于 `src/routes/` 中，文件名决定 URL 路径：文件名 |网址路径|目的 ---|---|--- `__root.tsx` |不适用 |根布局（始终呈现） `index.tsx` | `/` |索引路线 `about.tsx` | `/关于` |静态路由 `posts.tsx` | `/帖子` |布局路线（渲染Outlet） `posts.index.tsx` | `/帖子` |索引/帖子 `posts.$postId.tsx` | `/posts/:postId` |动态段 `_auth.tsx` |不适用 |无路径布局（包裹子项，无 URL） `_auth.dashboard.tsx` | `/仪表板` |无路径布局的子级 `posts_.$postId.edit.tsx` | `/posts/:postId/edit` |非嵌套（转义父布局） `文件.$.tsx` | `/文件/*` | Splat/catch-all 路线 `帖子。{-$category}.tsx` | `/posts/:类别？` |可选路径参数 `-utils.tsx` |不适用 |从路由中排除 `（组）/login.tsx` | `/登录` |路线组（仅限组织）该插件自动生成 `routeTree.gen.ts` \- 提交此文件，但切勿手动编辑它。 ## 导航从 '@tanstack/react-router' 导入 { Link, useNavigate } // 声明式 - 链接组件查看帖子第 2 页返回帖子 // 主动样式关于 // 编程 - useNavigate 常量导航 = useNavigate() 导航（{ 到：'/posts/$postId'，参数：{ postId：'123' } }）导航({ 到: '/posts', 搜索: (上一页) => ({ ...上一页, 页: 2 }) }) navigation({ to: '..', from: '/posts/$postId' }) // 相对 ## 搜索参数（经过验证且类型安全）从 '@tanstack/react-router' 导入 { createFileRoute } 从 'zod' 导入 { z } 导出 const 路由 = createFileRoute('/posts')({ validateSearch: z.object({ 页面：z.number().catch(1), 排序： z.enum(['asc', 'desc']).可选(), 过滤器：z.string().可选()， }), 组件：帖子页面， }) 函数 PostsPage() { const { page, sort, filter } = Route.useSearch() // 完全类型化常量导航 = Route.useNavigate() 返回（ ), }) // 路由器的全局默认值常量路由器 = createRouter({ 路线树， defaultNotFoundComponent: () =>

找不到页面

, defaultErrorComponent: ({ error }) =>

错误: {error.message}

, }) ## 基本挂钩钩|目的 ---|--- `Route.useSearch()` |当前验证的搜索参数 `Route.useParams()` |当前路径参数 `Route.useLoaderData()` |来自路线加载器的数据 `Route.useRouteContext()` |路线的上下文 `Route.useNavigate()` |从当前路线导航 `useNavigate()` |从任何组件导航 `useRouter()` |访问路由器实例 `useRouterState()` |反应式路由器状态 `useMatch({ from: '/route' })` |匹配特定路线的数据 `useBlocker()` |块导航（脏表单）请参阅“references/api-hooks.md”，了解所有 19 个具有完整签名的钩子。 ## 关键规则 * **插件顺序** : 在 Vite 配置中，`tanstackRouter()` 必须位于 `react()` 之前 * **提交routeTree.gen.ts** ：它是运行时代码，而不是构建工件 * **模块声明** : 始终注册路由器类型以进行全局类型推断 * **导出为路由** ：基于文件的路由必须导出 `const Route = createFileRoute(...)` * **无路径布局** ：前缀为“_”（例如，“_auth.tsx”），用于仅布局路由 * **非嵌套路由** ：使用 `_` 后缀来转义父布局（例如，`posts_.$id.edit.tsx`） * **忽略生成的文件** : 将 `routeTree.gen.ts` 添加到 `.prettierignore`、`.eslintignore` * **路由匹配顺序** : Index > Static > Dynamic > Splat (自动) * **不要导出路由属性** ：导出的组件/加载器会破坏代码分割 * **验证适配器** ：Valibot/ArkType直接工作； Zod 需要 `zodValidator` 适配器 * **需要 Outlet** ：每条有子路由的路由都必须渲染 ``；没有“组件”自动渲染“”的路由 * **类型安全提示**：在独立钩子上使用“Route.useX()”方法进行自动类型推断 ## 参考文件 ### API * `references/api-hooks.md` — 所有 19 个带有签名、选项和示例的钩子 * `references/api-components.md` — Link、Outlet、Await、Block、HeadContent、CatchNotFound 等 * `references/api-functions.md` — createRouter、createFileRoute、重定向、notFound、linkOptions、搜索中间件 * `references/api-router-instance.md` — Router 实例方法、事件和路由类型 API * `references/api-types.md` — NavigateOptions、RouterState、RouteMatch、类型实用程序、已弃用的项目 ### 模式 * `references/patterns-params.md` — 路径参数、搜索参数 (Zod/Valibot/ArkType)、loaderDeps、中间件 * `references/patterns-links-blocking.md` — 链接选项、自定义链接、导航阻止、历史记录类型 * `references/patterns-data.md` — 数据加载、突变、TanStack 查询集成、未找到处理 * `references/patterns-auth.md` — 身份验证、RBAC、路由器上下文、预加载策略 ### 配置 * `references/config-bundlers.md` — Vite、Webpack、Rspack、esbuild、路由器 CLI 设置和插件选项 * `references/config-routing.md` — 文件命名约定、路由匹配、基于代码的路由 * `references/config-virtual-routes.md` — 虚拟文件路由、物理路由、__virtual.ts 子树 * `references/config-router-options.md` — 所有 createRouter() 选项：核心、预加载、数据加载、搜索、滚动、URL 行为 * `references/config-route-options.md` — 所有 createFileRoute/createRoute 选项：组件、搜索、加载器、生命周期、头、SSR * `references/config-devtools.md` — DevTools 模式、生产 devtools、IDE 配置 ### 高级 * `references/advanced-ssr.md` — SSR 流式/非流式、脱水/水合、延迟数据 * `references/advanced-code-splitting.md` — 自动/手动拆分、拆分分组、惰性路由 * `references/advanced-url-features.md` — URL 重写、路由屏蔽、自定义搜索序列化 * `references/advanced-optimization.md` — 类型安全、TS 性能技巧、渲染优化、视图转换 * `references/advanced-head-scroll.md` — 文档头管理、滚动恢复、i18n ### 运营 * `references/troubleshooting.md` — 常见问题解答、常见错误、调试指南、性能问题 * `references/deployment-integrations.md` — 部署（8 个平台）、环境变量、框架集成 * `references/testing-migration.md` — 测试设置、路由测试模式、迁移指南

Tanstack 路由器指南

包含技能