1. TanStack Start 在 TanStack 生态里的位置
你可以把 TanStack Start 理解成：把 TanStack Router + TanStack Query + React 打包成一个“有主见的全栈壳”，帮你从 SPA 升级到 SSR/SSG 的全栈应用。
官方简介里就强调了它是基于 TanStack Router 的全栈框架壳子（包括 SSR、静态预渲染、server functions 等）tanstack start 官网。
1.1 组合关系：Router / Query / Start
TanStack Start 自身并不重新发明路由或数据获取，它做的是“组合”和“约束”：
| 层级 | 角色 | 你写的代码主要长什么样 |
|---|---|---|
| React 组件 | 纯 UI | function UserList() { ... } |
| TanStack Query | 数据获取与缓存 | useQuery({ queryKey: ["users"], queryFn: getUsers }) |
| TanStack Router | 路由、布局、数据预取 | file-based routing 下的 routes/users.tsx 等 |
| TanStack Start | 执行模型、SSR/SSG、server functions、构建 | app.config, app/routes, app/server/functions 等 |
机制上：
- Router 决定“在哪个 URL 下渲染哪个页面组件”
- Query 决定“在这个页面里，数据怎么拉、怎么缓存”
- Start 决定“这些代码在什么环境（浏览器/Node/Edge）以什么模式（SSR/SSG/SPA）执行”
参考 LogRocket 的 TanStack Start 总览 可以看到，它基本是“给 TanStack Router 装了一个执行平台”。
1.2 一个可以运行的最小示例（概念级）
假设你有一个展示用户列表的页面：
tsx// app/routes/users.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'
import { getUsers } from '../server/functions/getUsers'
export const Route = createFileRoute('/users')({
component: UsersPage,
})
function UsersPage() {
const { data, isLoading } = useQuery({
queryKey: ['users'],
queryFn: () => getUsers(), // 注意：这里调用的是 server function
})
if (isLoading) return <div>Loading...</div>
return (
<ul>
{data?.map((u: any) => <li key={u.id}>{u.name}</li>)}
</ul>
)
}
ts// app/server/functions/getUsers.ts
'use server'
export async function getUsers() {
// 这里运行在 server runtime，可以访问 DB / 私钥等
return [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' },
]
}
关键点：
routes/users.tsx是 文件路由：文件 → 路由UsersPage是页面（React 组件）useQuery是 Query hook，用于获取数据getUsers是 server function，只在服务端执行
这一条链条就是后面你要画的“高层架构图”的骨架。
1 / 6