字
字节笔记本
2026年5月3日
TanStack Start - Routing 路由系统
API中转
¥120
TanStack Start 基于 TanStack Router，提供完整的类型安全路由功能。本文介绍路由配置、文件路由、嵌套路由等核心概念。
路由配置
Router 文件
router.tsx 文件定义 TanStack Router 在 Start 中的行为：
tsx
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
// 必须导出 getRouter 函数，每次返回新的路由实例
export function getRouter() {
const router = createRouter({
routeTree,
scrollRestoration: true,
})
return router
}可配置项:
- 默认预加载功能
- 缓存过期策略
- 滚动恢复、默认搜索参数等
文件路由
TanStack Start 使用 TanStack Router 的文件路由方法：
text
src/
├── routes <-- 路由存放目录
│ ├── __root.tsx
│ ├── index.tsx
│ ├── about.tsx
│ ├── posts.tsx
│ ├── posts.$postId.tsx根路由
根路由是整个路由树的顶层，封装所有其他路由：
特点:
- 无路径，始终匹配
component始终渲染- 渲染文档外壳（
<html>,<body>等） - 完美放置应用外壳和全局逻辑
tsx
// src/routes/__root.tsx
import {
Outlet,
createRootRoute,
HeadContent,
Scripts,
} from '@tanstack/react-router'
import type { ReactNode } from 'react'
export const Route = createRootRoute({
head: () => ({
meta: [
{ charSet: "utf-8" },
{
name: "viewport",
content: "width=device-width, initial-scale=1",
},
{ title: "TanStack Start Starter" },
],
}),
component: RootComponent,
})
function RootComponent() {
return (
<RootDocument>
<Outlet />
</RootDocument>
)
}
function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
return (
<html>
<head>
<HeadContent />
</head>
<body>
{children}
<Scripts />
</body>
</html>
)
}
<Scripts />必须放在<body>标签底部，用于加载客户端 JavaScript。
核心组件
HeadContent 组件
渲染文档的 head、title、meta、link 和 head-related script 标签：
tsx
<head>
<HeadContent />
</head>必须渲染在根路由布局的 <head> 标签中。
Outlet 组件
渲染下一个可能匹配的子路由：
tsx
<Outlet />- 不接受任何 props
- 可在路由组件树中任何位置渲染
- 无匹配子路由时渲染
null
Scripts 组件
渲染文档的 body 脚本：
tsx
<body>
{children}
<Scripts />
</body>必须渲染在根路由布局的 <body> 标签中。
路由树生成
自动生成的 routeTree.gen.ts 文件：
运行 TanStack Start 时自动生成（npm run dev 或 npm run start），包含：
- 生成的路由树
- 使类型安全极快且完全推断的 TS 工具
嵌套路由
TanStack Router 使用嵌套路由匹配 URL 与正确的组件树。
示例:
text
routes/
├── __root.tsx <-- <Root>
├── posts.tsx <-- <Posts>
├── posts.$postId.tsx <-- <Post>URL: /posts/123
组件树:
text
<Root>
<Posts>
<Post />
</Posts>
</Root>路由类型
| 类型 | 描述 | 示例 |
|---|---|---|
| Index Routes | URL 与路由路径完全匹配时匹配 | index.tsx |
| Dynamic/Wildcard/Splat Routes | 动态捕获部分或全部 URL 路径 | $postId.tsx, $.tsx |
实用路由类型
| 类型 | 描述 | 用途 |
|---|---|---|
| Pathless Layout Routes | 对一组路由应用布局或逻辑，不在路径中嵌套 | 共享布局 |
| Non-Nested Routes | 从父级取消嵌套路由，渲染自己的组件树 | 独立页面 |
| Grouped Routes | 在目录中组织路由，不影响路径层次 | 组织代码 |
创建文件路由
路径到文件映射
| 路径 | 文件名 | 类型 |
|---|---|---|
/ | index.tsx | Index Route |
/about | about.tsx | Static Route |
| - | posts.tsx | "Layout" Route |
/posts/ | posts/index.tsx | Index Route |
/posts/:postId | posts/$postId.tsx | Dynamic Route |
/rest/* | rest/$.tsx | Wildcard Route |
定义路由
使用 createFileRoute 函数导出 Route 变量：
tsx
// src/routes/posts/$postId.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
component: PostComponent,
})传递给
createFileRoute的路径字符串由 TanStack Router Bundler Plugin 或 Router CLI 自动写入和管理。
关键要点
- Router 配置:
router.tsx定义路由行为 - 文件路由: 在
src/routes目录创建文件 - 根路由:
__root.tsx始终渲染，包含文档外壳 - 核心组件:
HeadContent,Outlet,Scripts - 自动生成:
routeTree.gen.ts运行时生成
路由结构示例
text
src/routes/
├── __root.tsx # 根布局
├── index.tsx # 首页 (/)
├── about.tsx # 关于页 (/about)
├── posts.tsx # 文章列表 (/posts)
└── posts.$postId.tsx # 文章详情 (/posts/:postId)分享: