1. TanStack 生态总览

1.1 TanStack 是什么

TanStack 是一组**框架无关（framework-agnostic）**的前端开源库，由 Tanner Linsley 发起并维护。它不是单一框架，而是一整条工具链，覆盖了数据请求、路由、表格、表单、虚拟化等前端高频场景。

有个容易混的点先说清楚：早期大家都叫它 React Query，因为最初只有 React 适配器。从 v4 起正式改名 TanStack Query，现在它同时支持 React、Vue、Solid、Svelte、Angular 等多个框架。本教程以 React 适配器为主线，其他框架的用法大同小异。

TanStack 的核心理念有三条，后面会单独展开讲：

• headless（无头）：只给你逻辑和状态，UI 长什么样你自己定
• 框架无关：核心逻辑用纯 TypeScript 写，再套一层薄薄的框架适配器
• 类型安全：TypeScript 写的，能自动推导的类型绝不让你手写泛型

1.2 九大库一览

先看一张全家福，心里有个数。版本号是 2026 年 7 月实查的稳定版。

库	包名	版本	成熟度	干什么
Query	@tanstack/react-query	5.101.4	稳定 v5	服务端数据的请求、缓存、同步
Router	@tanstack/react-router	1.170.18	稳定 v1	类型安全的路由方案
Start	@tanstack/react-start	1.168.32	v1 RC	基于 Router + Vite 的全栈框架
Table	@tanstack/react-table	8.21.3	稳定 v8	headless 表格引擎
Form	@tanstack/react-form	1.33.2	稳定 v1	受控表单状态管理
Virtual	@tanstack/react-virtual	3.14.8	稳定 v3	虚拟化长列表
Store	@tanstack/store	0.11.0	v0	响应式状态管理（底层依赖）
DB	@tanstack/react-db	0.1.95	v0 早期	客户端数据库 + live queries
Pacer	@tanstack/react-pacer	0.22.1	v0	防抖、节流、限流

另外还有个 Ranger（滑块组件），目前才 0.0.5，极早期，教程里只在总览提一句，不单独成章。

1.3 各库定位详解

Query：服务端状态管家

绝大多数前端项目最头疼的不是写组件，而是管数据。接口请求、缓存、重试、loading 状态、刷新时机……自己手写一套很快就会变成屎山。

Query 把这些都接管了。你只要告诉它「查什么」（queryKey）和「怎么查」（queryFn），剩下的事——缓存共享、自动重试、后台刷新、失效管理——它都帮你做。

适用场景：任何需要从服务端拿数据的应用，基本都该上。

Router：类型安全路由

React Router 你肯定用过。TanStack Router 想解决的是 React Router 的几个老问题：类型不安全、search params 没约束、数据加载和路由耦合松散。

它支持文件式路由和代码式路由两种写法，路由参数、搜索参数全都有类型推导。还能和 Query 配合，在路由 loader 里预取数据。

适用场景：新项目想要类型安全路由，或者对 search params 校验有强需求。

Start：全栈框架

Start 是建在 Router 和 Vite 之上的全栈框架，定位类似 Next.js。它提供 SSR、Server Functions（服务端函数）、部署方案等能力。

如果你已经用了 TanStack Router，想再加全栈能力，Start 是顺理成章的升级路径。它和 Router 共享版本线，API 相对稳定了但迭代仍快。

适用场景：需要 SSR 或全栈能力的 React 项目，且已经在用 TanStack Router。

Table：表格引擎

注意它不是「表格组件」，而是「表格引擎」。它不渲染任何 DOM，只给你状态和逻辑：排序、过滤、分页、分组、列固定、行选择……你自己拿这些数据去渲染 <table>。

好处是完全可控，Tailwind、Material UI、shadcn/ui 随便配。坏处是上手比开箱即用的组件库陡，得自己写渲染逻辑。

适用场景：需要高度定制表格，或者表格交互复杂（排序+过滤+分页+虚拟化全都要）。

Form：受控表单

和 React Hook Form 的定位有点像，但 TanStack Form 走的是完全受控路线，类型推导更激进——深层次嵌套字段也能自动推导，不用手写泛型。支持同步/异步校验、schema 校验（zod/valibot）。

适用场景：表单逻辑复杂，或者想要更激进的类型安全。

Virtual：虚拟化列表

万条数据渲染成 DOM 浏览器会卡死。虚拟化的思路是只渲染可视区域的那几十条，滚动时动态替换。Virtual 就是干这个的，和 Table 配合能做大数据表格。

适用场景：长列表、大数据表格、任何 DOM 节点过多的场景。

Store / DB / Pacer：生态补充

• Store：轻量响应式状态管理，是其他库的底层依赖，也能单独用
• DB：客户端数据库 + live queries，v0 早期，概念比较前沿
• Pacer：防抖节流工具，小而精

1.4 怎么选型

选型这事别贪多。先想清楚你的痛点在哪。

如果你只是写个后台管理系统，Query + Table 基本够用了。数据请求用 Query，列表展示用 Table，剩下的用 React 自带的状态就行。

如果是新项目想要全套类型安全体验，Router + Query 是黄金组合。Router 管路由和预取，Query 管缓存，两者集成得很顺。

如果要做全栈应用、需要 SSR，再加 Start。但它迭代快，建议先跑通 Router + Query 再上。

1.5 和竞品对比

光说自己的好不行，得横向比一比。

数据请求：Query vs SWR vs RTK Query vs Apollo

能力	TanStack Query	SWR	RTK Query	Apollo
框架支持	React 等	React	Redux 生态	GraphQL
缓存策略	层级键值对	单键值对	单键值对	规范化 Schema
自动垃圾回收	有	无	有	无
窗口聚焦重取	有	有	有	无
查询取消	有	无	无	无
Devtools	有	有	有	有
乐观更新	有	弱	有	有
规范化缓存	无	无	无	有

Query 的优势是功能最全、默认行为最合理。SWR 更轻量但功能少；RTK Query 绑定 Redux 生态；Apollo 专精 GraphQL 但重。

路由：Router vs React Router

React Router 胜在生态成熟、用的人多。Router 胜在类型安全——路由参数、search params 全有类型，写错路径编译就报错。新项目可以试 Router，老项目没必要硬迁。

表格：Table vs ag-Grid

ag-Grid 是开箱即用的大型表格组件，功能多但要按它的样式走，企业版还收费。Table 是 headless 的，完全自由但要自己写渲染。定制需求强选 Table，想省事选 ag-Grid。

1.6 适用场景总结

TanStack 适合这几类项目：

• 中大型后台管理系统：Query + Table 是标配
• 对类型安全有强要求的团队：Router + Query + Form 全套类型推导
• 需要高度定制 UI 的项目：headless 设计让你完全掌控样式
• 多框架技术栈：核心逻辑可复用，换框架只换适配器

不太适合的场景：

• 极简静态页面：杀鸡用牛刀
• 对 bundle size 极度敏感的移动端 H5：Query 大约 13KB，Table 开全功能约 20KB，小项目可能嫌重
• 团队完全不用 TypeScript：TanStack 的一半价值在类型推导上

1.7 小结

TanStack 是一套框架无关、headless、类型安全的前端库族。核心成员是 Query（数据请求）、Router（路由）、Table（表格）、Form（表单）、Virtual（虚拟化），加上 Start（全栈）、Store（状态）、DB、Pacer 等补充。

选型原则：按需引入，先解决最痛的点。下一篇我们聊聊 headless 理念和框架无关设计，这是理解整个 TanStack 生态的钥匙。