TanStack 生态系统实战指南

TanStack 是一套无头（headless）、类型安全、可组合的库集合，涵盖数据获取、路由、表格、表单、虚拟化和客户端状态管理等功能。该生态系统起源于 React Query（现已更名为 TanStack Query）。其数据与 UI 库提供了适用于 React、Vue、Solid、Svelte 和 Angular 的适配器，而其路由器和全栈框架则专注于 React 和 Solid。TanStack 本身并非一个框架；该项目将其各组件定位为无头、可组合的工具集，其中只有 TanStack Start 是一个完整的全栈框架。

如果你已经在使用 TanStack Query，并不断看到 Router、Start、Table、Form、Store、DB 和 AI 这些名称被提及，实际问题在于：如何搞清楚每个库的功能、成熟度，以及何时应该选择它而非 React 默认技术栈（Next.js、React Router、Redux/Zustand、React Hook Form、Apollo、AG Grid）。本指南逐一梳理生态系统中的各个库，为每个库提供最简代码示例，以版本号标注成熟度，并展示各组件之间的协作关系。这是一份导览地图，而非教程——安装配置步骤请参阅文中链接的官方文档。

TanStack 是什么，“无头”为何重要

TanStack 是一套遵循同一设计原则的独立库集合：库负责逻辑，你负责渲染。每个 TanStack 库都将状态与标记分离——库运行状态机，你的组件决定界面的呈现方式。这就是”无头”在实践中的含义：没有需要覆盖的 TanStack CSS，没有需要继承的 TanStack 组件，也没有关于 UI 外观的任何厂商预设。TanStack Query 是这一品牌的起源——它从 React Query 更名而来，标志着生态系统的壮大——尽管 TanStack Table 早于品牌重塑就已存在，因此 Query 是推广意义上的起源，而非字面上的第一个库。

这一共同理念通常被概括为”拥有你的代码，而非你的框架”。由此衍生出三个特性：

• 无头（Headless）：只有逻辑，没有 UI。你将库的状态接入你已有的任意标记、设计系统或无障碍访问层。
• 框架无关的核心：数据与 UI 库——Query、Table、Form、Virtual 和 Store——提供适用于 React、Vue、Solid、Svelte 和 Angular 的官方适配器。路由是例外：TanStack Router 和 TanStack Start 仅支持 React 和 Solid。
• 可组合性优于单体架构：每个库既可独立使用，也可协同工作。你可以只引入 Query 而不引入 Router，或只引入 Table 而不引入 Start。

逐库导览

以下每个库的介绍涵盖其功能、所替代的方案、截至 2026 年 6 月的成熟度，以及最简代码示例。这些示例展示的是 API 接口，而非安装教程——请参阅链接的官方文档进行安装和配置。

TanStack Query — 服务端状态管理

TanStack Query 负责管理异步服务端状态：数据获取、缓存、后台重新获取、请求去重和乐观更新。它替代了大多数 React 应用最初采用的手动 fetch + useEffect 模式。目前已达到稳定版。

// @tanstack/react-query v5.101.0
const { data: users, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then((res) => res.json()),
});

Query 是进入该生态系统最广泛的切入点，也是对现有 React 代码库改造中投入产出比最高的变更——它无需触动路由或 UI 层，即可消除手写的加载和错误状态处理代码。

TanStack Router — 类型安全路由

TanStack Router 是一个面向 React 和 Solid 的全类型安全客户端路由器。路由路径、URL 参数、搜索参数、路由上下文和加载器数据均实现端到端类型化，因此参数形状错误的链接会在编译期被编译器捕获，而非在运行时被用户发现。它替代 React Router 用于单页应用（SPA），目前已达到稳定版。

// @tanstack/react-router v1.170.16
const Route = createFileRoute('/products')({
  validateSearch: (search) => ({
    category: (search.category as string) ?? 'all',
    page: Number(search.page ?? 1),
  }),
});

const { category, page } = Route.useSearch();

Router 将 URL 搜索参数视为经过类型化和验证的状态，使过滤条件、排序方式和分页信息可通过 URL 共享，并在刷新后恢复。这解决了一类具体且可复现的 Bug：对 SPA 仪表盘的会话回放分析中，经常可以发现用户在刷新或后退导航时丢失过滤、排序和分页状态——这正是因为这些状态存储在组件内存而非 URL 中，而类型化搜索参数恰好消除了这一故障模式。

TanStack Table — 无头数据表格

TanStack Table 处理数据表格的逻辑——列定义、排序、过滤、分页、行选择、分组和列可见性——同时将所有像素级的 UI 交由你来决定。它在 React 生态系统中确立了无头模式，替代了 AG Grid 和 MUI DataGrid 等有主见的表格库，适合希望完全掌控标记的团队。目前已达到稳定版，V9 版本线正在开发中，尚未发布为 latest。

// @tanstack/react-table v8.21.3
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

Table 实例负责管理状态，你的标记负责渲染该状态所描述的内容。结合 Query 实现服务端分页和过滤，可在不将全部数据加载到客户端的情况下处理大型数据集。

TanStack Form — 类型化表单

TanStack Form 负责管理表单状态和验证——字段级和表单级错误、同步与异步验证、提交状态——而不渲染任何内容。它是 React Hook Form 的无头继任者，目前已达到稳定版（v1）。

// @tanstack/react-form v1.33.0
const form = useForm({
  defaultValues: { email: '', password: '' },
  onSubmit: async ({ value }) => { await loginUser(value); },
});

字段值、验证 schema 和提交载荷均实现端到端类型化，异步验证（例如检查用户名是否可用）是一等功能，防抖和取消逻辑由库自行处理。

TanStack Virtual — 列表与表格虚拟化

TanStack Virtual 针对大型可滚动列表和表格，仅渲染当前视口内的行或列，在数据集保持庞大的同时维持较小的 DOM 规模。它提供测量值和偏移量，由你来渲染标记。它替代了手写的窗口化方案以及 react-window、react-virtualized 等库。目前已达到稳定版。

// @tanstack/react-virtual v3.14.3
const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 48,
});

const rows = virtualizer.getVirtualItems();

useVirtualizer 返回视口内的虚拟条目及总高度，你通过绝对定位按偏移量渲染每个条目。它与 Table 天然配合——Table 负责行模型，Virtual 只将可见行保留在 DOM 中——因此五千行的列表也能以满帧速度滚动。

TanStack Store — 客户端状态

TanStack Store 是一个细粒度响应式状态库，为其他多个 TanStack 库的内部实现提供支持，并作为独立包对外暴露。它为客户端（非服务端）状态提供了 Zustand 和 Redux 的替代方案。作为独立包，它目前处于 alpha 阶段（v0.11.0），因此对于”替代 Zustand/Redux”的说法，需结合其成熟度审慎对待。

// @tanstack/store v0.11.0 + @tanstack/react-store
import { Store } from '@tanstack/store';
import { useStore } from '@tanstack/react-store';

const countStore = new Store(0);
// 在组件中：
const count = useStore(countStore);

职责划分是有用的思维模型：Query 负责服务端状态，Store 负责客户端状态。对于大多数应用，Query 加上少量 Store（或你现有的客户端状态工具）即可覆盖完整的状态管理需求。

TanStack Start — 全栈框架

TanStack Start 是一个基于 TanStack Router 构建的全栈 React 框架。它提供基于文件的路由、服务端函数、流式 SSR 和端到端 TypeScript，同时保持底层机制的透明可见。它与 Next.js 和 Remix 形成竞争关系。Start 目前处于候选发布（Release Candidate）阶段（当前发布线为 1.168.x），尚未宣布稳定，其 React Server Components 支持以实验性方式提供，而非作为生产默认选项。

// @tanstack/react-start v1.168.26
import { createServerFn } from '@tanstack/react-start';

const getUser = createServerFn({ method: 'GET' })
  .validator((userId: string) => userId)
  .handler(async ({ data: userId }) => db.users.findById(userId));

服务端函数是类型化的、与业务代码共置的函数，在服务端执行，但从客户端组件调用时与普通异步函数无异——类型从数据源流向组件，无需手动标注，对于简单的数据获取场景也无需维护独立的 API 层。注意导入路径为 @tanstack/react-start；显示 @tanstack/start 的旧版指南已过时。

TanStack DB — 响应式客户端存储

TanStack DB 是一个响应式、客户端优先的存储层，具备集合（collections）、实时查询（live queries）和乐观更新（optimistic mutations）功能。你定义集合，针对集合编写查询，任何观察该查询的组件在底层数据发生变化时——无论来自服务端同步、本地变更还是乐观更新——都会重新渲染。它位于你自己的后端或 API 之前，是一个客户端存储/同步层，而非 Firebase 或 Supabase 这类后端即服务（BaaS）的替代品。目前处于 beta 阶段（v0.6.9）。

DB 填补了单纯 fetch-and-cache 之外的空白：适用于具有实时更新、复杂客户端过滤和多用户状态的数据密集型应用。“无头 Firebase”的类比是对其响应式查询模型的比喻，并非对托管基础设施的替代声明。

TanStack AI — 提供商无关的 AI 原语

TanStack AI 提供用于 AI 功能的无头原语——流式响应处理、对话状态管理，以及跨模型提供商的统一接口——而不将你锁定于单一 SDK 或提供商。它目前处于 beta 阶段，详见 TanStack 博客公告，并非 alpha 或实验性阶段。

流式响应（token 逐步到达）得到原生支持，这正是 AI 对话和生成界面呈现出响应感的关键所在。其价值在于架构层面：提供商无关的抽象层使你能够在不重写 UI 状态的情况下自由切换模型提供商。

成熟度一览表

生态系统各成员的成熟度差异显著，生态系统概览中最常见的错误是将实验性库呈现为已成熟的方案。本文涵盖的九个库中，截至 2026 年 6 月，Query、Router、Table、Form 和 Virtual 已达到稳定版；Start 处于候选发布阶段，React Server Components 支持以实验性方式提供；DB 和 AI 处于 beta 阶段；Store 处于 alpha 阶段。下表记录了每个库的已发布版本和状态。

请查阅链接文档以获取最新发布状态。

各组件如何协同工作

这些库在设计上支持组合使用，核心集成方式是通过 Router 加载器预取 Query 数据，使组件在渲染时命中热缓存。路由加载器可以在组件挂载前调用 queryClient.ensureQueryData；待组件渲染时，数据已在缓存中就绪。当 Start 为该流程加入 SSR 时，数据会在服务端预加载并脱水（dehydrated），在首次请求时以完整渲染的 HTML 形式到达客户端。

// @tanstack/react-router v1.170.16 + @tanstack/react-query v5.101.0
const Route = createFileRoute('/users/$userId')({
  loader: ({ params }) =>
    queryClient.ensureQueryData({
      queryKey: ['user', params.userId],
      queryFn: () => fetchUser(params.userId),
    }),
  component: UserPage,
});

以下三个具体的集成关系值得特别说明：

1. Router → Query：路由加载器预取 Query 数据，消除首次渲染时的加载闪烁。
2. Start → Router：Start 基于 Router 构建，因此类型化路由和加载器模型直接延伸至全栈框架，并在此基础上增加了 SSR 和脱水功能。
3. Table → Query：Table 消费来自 Query 的分页、过滤数据，实现服务端分页，使表格在不将全部数据拉取到客户端的情况下处理大型数据集。

如何在 TanStack 与现有方案之间做选择

对于需要被索引和分享的公开页面，选择 TanStack Start；对于 SEO 无关紧要、客户端性能是优先考量的已认证仪表盘，单独使用 TanStack Router。这一渲染策略决策是首要的架构选择，先于任何库的选型——这是产品决策，而非技术偏好。

• 面向公众的站点（营销页面、博客、内容产品）需要 SSR。爬虫无法可靠地执行 JavaScript；LCP、CLS 和 INP 等核心网页指标（Core Web Vitals）是 Google 的排名信号；Open Graph 元数据从服务端响应中读取。Start 在首次请求时即可提供完整渲染的 HTML。
• 已认证应用（仪表盘、内部工具、客户门户）本就无法被爬取，基于会话且有状态，优先考量的是可交互时间（time-to-interactive）。单独使用 Router 的 SPA——不引入 Start 的 SSR 机制——往往更为轻量。

对于库与现有方案的选择，该生态系统与 React 默认技术栈的对应关系如下：

何时不应使用 TanStack

TanStack 的无头、类型安全模型是一个有力的默认选择，但在三种情况下会成为真正的负担，一份诚实的指南应当明确指出这些情况。当你的团队需要开箱即用的预置样式组件、当你的招聘候选人熟悉 Redux 和 React Router 而非 TanStack，或者当你今天就需要在生产环境中使用稳定的 React Server Components 时，该模型并不适合——因为 Start 中的 RSC 支持仍处于实验阶段，在这些情况下 Next.js 和 React Hook Form 仍是更务实的选择。

具体而言：

• 需要预置样式组件：无头意味着你需要自行构建 UI。如果你希望表格或表单在安装后即呈现完整外观，AG Grid、MUI 或组件库会更快。
• 团队熟悉度与招聘：更多开发者熟悉 Redux、React Router 和 Next.js。学习曲线和较小的人才池对团队扩张而言是真实的成本。
• 今日生产环境中的 RSC：Next.js 在 React Server Components 方面已有多年生产环境实战验证；截至 2026 年 6 月，Start 的 RSC 支持仍处于实验阶段。
• 早期阶段的库：Store（alpha）、DB（beta）和 AI（beta）尚未达到生产默认标准。引入时请结合其成熟度审慎评估，并关注链接文档中的版本和状态信息。

除本文涵盖的库之外，TanStack 还维护着一套工具层——包括 Virtual、Pacer、Ranger 和 DevTools——遵循相同的无头、类型安全模式，但作用范围更小。

从哪里开始

如果你还没有使用 Query，先从它开始——它是对 React 代码库改造中投入产出比最高的变更，且不会将你锁定于生态系统中的其他任何库。对于全新的 SPA，选择 Router 而非迁移现有应用；对于需要 SSR 的新公开站点，将 Start 作为首选，同时关注其 RC 状态。对于早期阶段的库——Store、DB 和 AI——应以有时效性的成熟度表格和链接的官方文档为准，而非生态系统的炒作，来判断某个库是否已准备好承担你所设想的角色。

常见问题

TanStack Query 和 TanStack DB 有什么区别？

TanStack Query 通过数据获取、缓存、后台重新获取和请求去重来管理异步服务端状态，将服务端视为客户端所镜像的数据源。TanStack DB 是一个响应式、客户端优先的存储层，具备集合、实时查询和乐观更新功能，位于你自己的后端之前，适用于具有实时更新和复杂客户端过滤的数据密集型应用。截至 2026 年 6 月，Query 已达到稳定版，DB 处于 beta 阶段。

我可以在 Vue、Svelte 或 Angular 中使用 TanStack 库，而不是 React 吗？

数据和 UI 库可以。Query、Table、Form、Virtual 和 Store 提供适用于 React、Vue、Solid、Svelte 和 Angular 的官方适配器。路由是例外：TanStack Router 和 TanStack Start 全栈框架仅支持 React 和 Solid。因此，Vue 或 Angular 团队可以引入 Query 和 Table，但无法使用 TanStack Router 实现类型安全路由。

TanStack Start 是否已可作为 Next.js 的生产替代方案？

截至 2026 年 6 月，尚未完全达到。TanStack Start 处于 1.168.x 发布线的候选发布阶段，尚未宣布稳定，其 React Server Components 支持仅以实验性方式提供，而非作为生产默认选项。如果你今天就需要在生产环境中使用稳定的 RSC，Next.js 在该功能上已有多年实战验证。对于可接受实验性 RSC 的新公开 SSR 站点，Start 是合理的选择。

我必须采用整个 TanStack 生态系统才能使用其中一个库吗？

不需要。每个 TanStack 库都是独立且可组合的，因此你可以只引入 Query 而不引入 Router，或只引入 Table 而不引入 Start。这些库在协同使用时可以集成（例如，路由加载器可以预取 Query 数据），但没有任何一个库依赖其他库。Query 是最常见的切入点，因为它是对现有 React 代码库改造中投入产出比最高的变更，且不会将你锁定于生态系统中的其他任何库。