概述

TanStack Router 是一款为构建 React 和 Solid 应用而生的路由库。其核心特性包括：

• 100% 类型推断的 TypeScript 支持
• 类型安全的导航
• 嵌套路由与布局路由（支持无路径布局）
• 内置路由加载器与 SWR 缓存
• 专为客户端数据缓存设计（兼容 TanStack Query、SWR 等）
• 自动路由预加载
• 异步路由组件与错误边界
• 基于文件的路由生成
• 类型安全的 JSON 优先搜索参数状态管理 API
• 路径与搜索参数的模式校验
• 搜索参数导航 API
• 自定义搜索参数解析器/序列化器支持
• 搜索参数中间件
• 路由匹配/加载中间件

快速入门请前往下一页。若需深入了解，请做好准备，我将带您全面解析！

在技术选型中，使用路由库构建应用已被视为必备选择，通常也是您技术栈中的首要决策之一。

那么，为何要选择 TanStack Router 而非其他方案？

要回答这个问题，我们需要审视当前生态中的其他选项。虽然仔细寻找会有许多选择，但根据经验，真正值得深入研究的仅有少数：

• Next.js - 作为新 React 项目的事实标准框架，它聚焦性能、工作流和前沿技术。其 API 与抽象虽强大，但有时显得非标准化。行业的快速发展和采用使其功能丰富，但也可能让人感到臃肿和难以驾驭。
• Remix / React Router - 基于历史悠久的 React Router 构建的全栈框架，提供同样强大的开发者与用户体验，其 API 和愿景根植于 Request/Response 等 Web 标准，并专注于能在任何 JS 环境中运行。其许多 API 和抽象设计精良，更是 TanStack Router 部分 API 的灵感来源。但其严格的设计、后补的类型安全以及对平台 API 的过度恪守，可能让部分开发者感到局限。

这些框架（及其路由方案）都很优秀，我个人可以证明它们都是构建 React 应用的优质解决方案。但经验也告诉我，这些方案尤其在路由 API 方面仍有巨大提升空间——开发者需要这些 API 来让应用更快、更简单、更愉悦。

毫不意外，选择路由库如此重要，以至于它通常与框架选择紧密绑定，因为多数框架都依赖特定的路由方案。

这是否意味着 TanStack Router 是一个框架？

传统意义上，TanStack Router 并非“框架”，因为它不涉及其他常见的全栈关注点。但它的设计允许通过与处理打包、部署和服务端功能的工具结合，升级为全栈框架。为此我们正在开发 TanStack Start——一个基于 TanStack Router 及 Nitro、Vite 等工具构建的全栈框架。

若想深入了解 TanStack Router 的历史，可阅读 TanStack Router 发展历程。

TanStack Router 满足您对其他路由库的所有基本期待：

• 嵌套路由、布局路由、分组路由
• 基于文件的路由
• 并行数据加载
• 预加载
• URL 路径参数
• 错误边界与处理
• SSR
• 路由伪装

同时它还带来提升标准的新特性：

• 100% 类型推断的 TypeScript 支持
• 类型安全的导航
• 加载器内置 SWR 缓存
• 为客户端数据缓存设计（兼容 TanStack Query、SWR 等）
• 类型安全的 JSON 优先搜索参数状态管理 API
• 路径与搜索参数的模式校验
• 搜索参数导航 API
• 自定义搜索参数解析器/序列化器支持
• 搜索参数中间件
• 继承式路由上下文
• 文件与代码混合路由

让我们深入探讨其中几个重要特性！

如今所有项目都宣称“用 TypeScript 编写”或至少提供类型定义，但真正为 TypeScript 设计 API 的生态包却寥寥无几。虽然您的路由库能自动补全选项字段并捕捉一些属性/方法拼写错误，但潜力远不止于此。

• TanStack Router 在代码任意位置都能完全感知所有路由及其配置，包括路径、路径参数、搜索参数、上下文等。这意味着您可以 100% 类型安全地导航到任何路由，确保链接或导航调用必然成功。
• TanStack Router 提供无损类型推断。它通过无数泛型参数将您提供的类型信息强制传播到整个 API 和应用中。这是其他路由库无法提供的类型安全级别和开发者信心。

这对您意味着：

• 通过自动补全和类型提示加速功能开发
• 更安全快速的代码重构
• 确保代码按预期运行

搜索参数常被事后考虑，被视为可解析更新的字符串黑箱（或字符串数组），仅此而已。现有方案并非类型安全，增加了处理它们的谨慎需求。即使最“现代”的框架和路由库也将管理此状态的工作留给您。它们可能将搜索字符串解析为对象，或让您用 URLSearchParams 自行处理。

但请记住：搜索参数是您应用中功能最强大的状态管理器。它们是全局的、可序列化、可书签化且可分享的，是存储需持久化或社交分享状态的完美场所。

为承担这一责任，搜索参数在 TanStack Router 中是一等公民。基于标准 URLSearchParams 的同时，它通过强大解析器/序列化器管理更深层复杂的数据结构，同时保持类型安全和易用性。

就像在 URL 中拥有 useState！

搜索参数具备：

• 自动 JSON 解析与序列化
• 验证与类型化
• 从父路由继承
• 在加载器、组件和钩子中可访问
• 通过 useSearch 钩子、Link、navigate 和 router.navigate API 轻松修改
• 支持自定义搜索过滤器和中间件
• 可通过细粒度选择器订阅以实现高效重渲染

一旦使用 TanStack Router 的搜索参数，您将惊叹以往如何能缺少它们。

数据加载是任何应用的关键部分，虽然多数路由库提供关键数据加载 API，但在缓存和数据生命周期管理上常有不足。现有方案存在几个通病：

• 无缓存。数据始终新鲜，但用户需反复等待频繁访问的数据加载。
• 过度缓存。数据缓存过久导致陈旧和糟糕体验。
• 生硬的失效策略和 API。数据可能频繁失效导致多余网络请求，或您可能完全无法精细控制失效时机。

TanStack Router 通过双重策略解决这些问题：

提供轻量级内置缓存层，与路由无缝协作。此缓存层松散基于 TanStack Query，但功能更少、API 更精简。与 TanStack Query 类似，合理而强大的默认值确保数据被缓存复用、适时失效、闲置时垃圾回收，并提供手动失效 API。

设计上便于与现有数据获取库（如 TanStack Query、SWR、Apollo、Relay 或自定义方案）集成。context、beforeLoad、loaderDeps 和 loader 等可配置 API 协同工作，轻松定义声明式数据依赖、预加载数据并管理外部数据源生命周期。

TanStack Router 的路由上下文是强大功能，允许定义特定于路由的上下文，并被所有子路由继承。路由器和根路由本身也能提供上下文。上下文可同步或异步构建，用于共享数据、配置甚至函数。这在以下场景特别有用：

• 认证与授权
• 混合 SSR/CSR 数据获取与预加载
• 主题化
• 单例与全局工具
• 在预加载、加载和渲染阶段进行柯里化或部分应用

当然，路由上下文也完全类型安全且零成本推断。

TanStack Router 同时支持基于文件和代码的路由。这种灵活性让您选择最适合项目需求的方式。

其文件路由方案独特地面向用户：路由配置由 Vite 插件或 CLI 生成，但生成代码的使用完全由您掌控！这意味着即使使用文件路由，您也始终完全掌握路由和路由器。

TanStack Router 借鉴了许多 OSS 项目的理念与模式，包括：

• TRPC
• Remix
• Chicane
• Next.js

我们认可这些项目开发中的投入、风险和研究，并期待将它们设立的标准推向更高。

概述已足够，TanStack Router 还有更多可能。点击下一页，让我们启程！