开发工具精选项目

TanStack Router

面向 React 与 Solid 的类型安全路由器，覆盖文件路由、Search Params、数据加载、预加载和代码分割。

GitHub 访问官网

主要语言TypeScript

开源许可MIT

项目类型开发工具

维护状态活跃维护

OVERVIEW

项目概述

TanStack Router 把路径参数、查询参数、链接、导航和 Loader 纳入同一套 TypeScript 类型系统。它支持文件式与代码式路由，并可与 TanStack Query、Vite 及 TanStack Start 组合。

TanStack Router 是 TanStack 维护的 MIT 开源路由器，当前为 React 和 Solid 提供官方适配器。它不只是根据 URL 切换组件，还让 Route Tree 成为路径参数、Search Params、Loader、上下文、Link 与 Navigate 的类型来源。官方推荐文件式路由：构建插件会根据 src/routes 生成 routeTree.gen.ts，并可自动拆分各路由的非关键代码；需要更精细控制时，也可以完全使用代码式路由。它本身是客户端路由基础设施，并非后端或完整全栈框架；TanStack Start 则在它之上提供 SSR、Server Functions 等能力。

React 适配器1.170.18

支持框架React / Solid

路由方式文件式 / 代码式

FEATURES

主要特点

TanStack Router 围绕强类型 Route Tree，统一组织导航、URL 状态、数据加载与渲染边界。

端到端类型安全

Route Tree 会推导 Link、Navigate、路径参数、Search Params、Loader 数据和路由上下文，许多无效跳转能在编译期发现。

文件式路由

根据 src/routes 的文件与目录生成路由树，动态段、布局、无路径布局和路由组都能通过统一约定表达。

代码式路由

也可以使用 createRootRoute、createRoute 和 addChildren 显式构造路由树，适合不希望依赖文件约定的项目。

类型化 Search Params

以 JSON-first 模型处理 URL 查询参数，可保留数字、布尔值和嵌套结构，并通过 Zod、Valibot 等方案执行运行时验证。

路由级数据加载

beforeLoad、loader、依赖项和路由上下文把权限判断、数据准备与页面渲染边界放在一起。

预加载与缓存

可以在用户悬停、聚焦或触摸链接时按 Intent 预加载代码和数据，并使用路由缓存减少重复工作。

自动代码分割

构建插件可把关键路由配置与组件、错误边界等非关键内容拆开，让首屏只下载当前导航真正需要的代码。

嵌套路由与布局

父子路由通过 Outlet 组合共享布局，同时支持 Pathless Layout、Route Group 和非嵌套路由等组织方式。

完整渲染边界

路由可以定义 Pending、Error、Not Found 和 Suspense 边界，让加载与失败状态靠近对应页面。

导航体验能力

内置 Scroll Restoration、Route Masking、Navigation Blocking、Redirect 和活动链接状态等常用能力。

TanStack Query 集成

Loader 可使用 QueryClient.ensureQueryData 预取并复用服务端状态，减少进入页面后才发起请求的数据瀑布。

Devtools 与全栈延伸

官方 Devtools 可观察匹配和路由状态；需要 SSR 与 Server Functions 时，可继续采用基于 Router 的 TanStack Start。

USE CASES

适用场景

当 URL 承载较多业务状态、页面嵌套复杂或团队希望尽早发现错误时，它尤其有价值。

类型密集的 React SPA

适合希望重构路径、参数或 Loader 时由 TypeScript 找出受影响链接和页面的中大型应用。

筛选与搜索产品

电商、目录、报表和搜索页可把分页、排序、筛选器安全地编码进 URL，支持分享、刷新与浏览器前进后退。

SaaS 管理后台

嵌套布局、权限前置检查、面包屑和路由级数据加载适合组织多层级工作区与管理界面。

数据密集型应用

与 TanStack Query 配合，在导航开始时预取数据，统一缓存、新鲜度和错误边界。

需要精细分包的单页应用

自动代码分割与 Intent Preload 能在减少初始包体的同时，保持后续页面切换流畅。

带登录与角色路由的产品

通过 Router Context 和 beforeLoad 组织登录跳转与角色判断，同时由服务端继续执行真正的权限校验。

TanStack Start 全栈应用

Router 是 TanStack Start 的路由基础，熟悉其文件约定、Loader 与 Search Params 后可平滑扩展到 SSR。

EVALUATION

优点与注意事项

技术选型不仅要看能力，也要理解它带来的团队成本。

主要优点

TanStack Router 擅长的地方

路径、参数、Search Params、Link 和 Loader 共享一套类型来源
文件式与代码式路由并存，可按团队习惯选择
JSON-first Search Params 适合承载复杂、可分享的界面状态
Loader、预加载、缓存和错误边界覆盖完整导航生命周期
构建插件可自动生成路由树并执行路由级代码分割
与 TanStack Query 的预取、缓存和 SSR 工作流衔接紧密
React 与 Solid 适配器共享核心概念，TypeScript 体验一致
Devtools、CLI、文档和 TanStack Start 构成完整生态路径

需要注意

采用前应考虑的问题

当前只面向 React 与 Solid

Vue、Svelte 等项目不能直接使用对应的 UI 适配器；跨框架团队应先确认实际支持范围。

文件式路由依赖生成流程

需要正确配置 Vite、Rspack、Webpack 或 Esbuild 插件，并把 Router 插件放在 React 插件之前。生成文件不能手工维护。

Search Params 仍是不可信输入

类型推导不会替代运行时验证。来自地址栏或外部链接的数据应通过 validateSearch 和 Schema 校验、补默认值或拒绝。

Router 不是安全边界

beforeLoad 可以改善客户端导航体验，但不能保护接口和敏感数据；身份与权限必须由服务端再次校验。

需要设计数据缓存归属

Router 自带 Loader Cache，TanStack Query 也维护 Query Cache。团队应明确哪些数据由谁缓存，避免重复策略和失效不一致。

大型路由树要注意类型性能

过宽的联合类型、在组件中直接引用整个 Router 类型或不精确的 from 可能拖慢 TypeScript，应遵循官方类型安全建议。

预加载策略会消耗资源

Intent Preload 很方便，但大量链接、昂贵 Loader 或弱网场景需要设置 staleTime、preloadDelay 和缓存边界。

数据加载仍可能形成瀑布

如果父 Loader 完成后才发现子页面依赖，或组件挂载后才请求关键数据，路由能力也无法自动消除瀑布，应主动并行预取。

自动分包依赖受支持的构建插件

只安装 Router 核心包不会自动获得分包。启用 autoCodeSplitting 前还应检查 Chunk 数量和缓存策略。

完整 SSR 需要额外框架能力

TanStack Router 本身不是后端框架。需要流式 SSR、Server Functions 和部署适配器时，应评估 TanStack Start 或现有全栈框架。

包版本应保持协调

React Router 适配器、Router Plugin、Devtools 与 Start 更新较快，升级时应查看迁移说明并锁定依赖版本。

最低运行环境需要核对

@tanstack/react-router 1.170.18 的 npm 元数据要求 Node.js 20.19 或更高版本，现有项目和 CI 在升级前应先确认。

QUICK START

快速开始

下面以 React、Vite 和推荐的文件式路由为例，完成插件配置、根布局、动态路由、Router 注册和 Query 预取。

1使用官方 CLI 创建 Router 项目

bash

npx @tanstack/cli create my-router-app --router-only
cd my-router-app
npm install
npm run dev

2在现有 React + Vite 项目中安装

bash

npm install @tanstack/react-router
npm install --save-dev @tanstack/router-plugin @tanstack/react-router-devtools

3配置 Vite 与自动代码分割

typescript

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { tanstackRouter } from "@tanstack/router-plugin/vite";

export default defineConfig({
  plugins: [
    tanstackRouter({
      autoCodeSplitting: true,
    }),
    react(),
  ],
});

4创建根布局路由

tsx

import {
  createRootRoute,
  Link,
  Outlet,
} from "@tanstack/react-router";
import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";

export const Route = createRootRoute({
  component: () => (
    <>
      <nav>
        <Link to="/">首页</Link>
        <Link to="/projects">项目</Link>
      </nav>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
});

5创建带参数和 Search Params 的页面

tsx

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/projects/$projectId")({
  validateSearch: (search: Record<string, unknown>) => ({
    tab: search.tab === "activity" ? "activity" : "overview",
  }),
  loader: ({ params }) => getProject(params.projectId),
  component: ProjectPage,
});

function ProjectPage() {
  const project = Route.useLoaderData();
  const { tab } = Route.useSearch();

  return <h1>{project.name} · {tab}</h1>;
}

6创建并注册 Router

tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import {
  createRouter,
  RouterProvider,
} from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

const router = createRouter({
  routeTree,
  defaultPreload: "intent",
});

declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>,
);

7在 Loader 中预取 TanStack Query

typescript

export const Route = createFileRoute("/projects/$projectId")({
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(
      projectQueryOptions(params.projectId),
    ),
  component: ProjectPage,
});

function ProjectPage() {
  const project = Route.useLoaderData();
  return <ProjectDetails project={project} />;
}

8执行类型检查与构建

bash

npm run dev

# 发布前执行项目自己的检查
npm run typecheck
npm run build

下一步：优先让 URL 结构与产品信息架构保持一致，并在路由边界验证所有 Search Params。文件式路由生成的 routeTree.gen.ts 应交给插件维护，不要手工编辑。

ALTERNATIVES

类似项目

React、SolidJS 是当前官方支持的界面框架；TanStack Query 常与路由 Loader 配合，React Router 和 wouter 则代表不同取向的 React 路由方案。

React

用于构建 Web 和原生用户界面的组件化 JavaScript 库。

查看项目

SolidJS

采用细粒度响应式和 JSX 构建高性能 Web 用户界面的 JavaScript 库。

查看项目

TanStack Query

面向 Web 应用的异步服务端状态管理工具，统一处理请求缓存、同步、失效、Mutation 和后台更新。

查看项目

Vite

新一代前端构建工具，提供快速开发服务器和优化构建。

查看项目

React Router

React 生态中历史悠久的路由方案，既可作为声明式库，也可采用 Data Mode 或 Framework Mode。

访问官网

wouter

面向 React 与 Preact 的极简路由库，以小体积 Hook API 和低配置为主要特点。

访问官网

COMPARISON

TanStack Router vs React Router

TanStack Router 与 React Router 都能覆盖现代 React 路由和数据加载。前者把 TypeScript 推导、结构化 Search Params 与构建期路由生成放在核心位置；后者历史更久，并提供从轻量声明式用法到完整 Framework Mode 的多种采用层级。

比较维度	TanStack Router	React Router
核心定位	TypeScript-first 的强类型客户端路由器	React 通用路由库，并提供 Data / Framework Mode
类型来源	Route Tree 推导 Link、参数、Search、Loader 与 Context	可生成 Route Module 类型，具体能力随采用模式而变化
路由定义	推荐文件式生成，也支持完整代码式路由	JSX 声明、Route Object 或 Framework 文件约定
Search Params	JSON-first、Schema 验证与类型化读写	以 URLSearchParams 和 useSearchParams 为主
数据加载	beforeLoad、Loader、Context、Cache 与依赖项	Loader、Action、Fetcher、Revalidation 与 Middleware
预加载与缓存	Intent Preload 和内置 Route Cache，可接 Query	Data Router 管理加载与重验证，策略取决于模式
代码分割	构建插件可自动拆分 Route 的关键与非关键配置	支持 lazy Route，Framework Mode 提供自动分包
框架范围	官方支持 React 和 Solid	专注 React
全栈路径	通过 TanStack Start 扩展 SSR 与 Server Functions	Framework Mode 覆盖 SSR、预渲染和 Server Action
生态与成熟度	较新，TanStack 数据工具组合紧密	采用广泛、历史更久、迁移资料与集成丰富
更适合	重视 URL 类型安全、复杂 Search 与 Query 集成的团队	需要成熟生态、渐进采用或 React Router Framework 的团队

如何选择

如果 TypeScript 是核心约束，页面依赖复杂路径与筛选状态，并希望 Router 与 TanStack Query 深度协作，TanStack Router 更有吸引力；如果项目已有 React Router 基础、看重广泛生态，或需要从简单声明式路由逐步升级到 Data / Framework Mode，继续使用 React Router 通常成本更低。选择前应做一个包含认证、嵌套路由、错误边界和真实 Search Params 的小型原型。

VERIFICATION