速查表：Next.js 工程师看 TanStack
一句话
| 概念 | 正确理解 |
|---|
| TanStack Router | 类型安全 route tree + URL 状态 + loader 生命周期 |
| TanStack Query | server state 管理，不是路由数据加载的替身，也不是它的下属 |
| TanStack Start | 基于 Router 的全栈 React 框架，提供 SSR、server functions、middleware、部署适配 |
| Cloudflare 组合 | Workers runtime + bindings 让 server functions/loaders 能直接使用平台资源 |
Next.js → TanStack 迁移词典
| Next.js | TanStack | 注意 |
|---|
| app route/page | file route / code route | 文件路由生成 route tree，但仍显式创建 router |
| searchParams | validateSearch | 把 URL 输入变成可信 typed object |
| router.push 字符串 | Link/navigate with typed params/search | 减少手写 URL 错误 |
| page-level async fetch | Route.loader | 声明路由进入前的数据依赖 |
| loading.tsx/error.tsx | pendingComponent/errorComponent | route option 形式 |
| Server Actions | createServerFn | typed RPC + validator + middleware |
| fetch cache/revalidate | staleTime/gcTime + Query + HTTP cache | 缓存层更显式 |
| Vercel platform APIs | Cloudflare Workers bindings | D1/R2/KV/Queues/AI 等 |
选择规则
- 复杂 URL 状态：优先认真评估 TanStack Router。
- 复杂 mutation/server state：TanStack Query。
- 想跑 Cloudflare Workers 并用 bindings：TanStack Start + Cloudflare 很合理。
- 重度依赖成熟模板、RSC 主路径、Next 生态：Next.js 仍强。
最小 Cloudflare 配置
{
"name": "my-tanstack-start-app",
"compatibility_date": "2026-07-07",
"compatibility_flags": ["nodejs_compat"],
"main": "@tanstack/react-start/server-entry",
"observability": { "enabled": true }
}