tanstack-start

TanStack Start

基于 TanStack Router 构建的全栈 React 框架。通过 RPC 提供类型安全的服务端函数、SSR／流式传输、中间件组合，并支持部署到 Cloudflare Workers、Vercel、Netlify、AWS Lambda 等平台。

RC： TanStack Start 目前处于候选发布（Release Candidate）阶段。正式发布稳定版 1.0 之前，API 仍可能发生变化。

包： @tanstack/react-start

快速参考

模式	用途
createServerFn()	GET（默认）——幂等、可缓存的数据获取
createServerFn({ method: 'POST' })	更改数据的变更操作
.inputValidator(zodSchema)	在处理函数执行前验证输入
.handler(async ({ data }) => {})	使用类型化输入数据执行服务端逻辑
getRequest()	在处理函数／中间件中访问完整的传入 Request
getRequestHeader(name)	按名称读取单个请求标头
setResponseHeaders(headers)	设置传出的响应标头（缓存、Cookie）
useServerFn(fn)	封装服务端函数，供组件使用并提供待处理状态
createMiddleware().server(fn)	用于横切关注点的请求中间件
.middleware([dep])	使用依赖项组合中间件
next({ context: {} })	通过中间件链向下游传递数据
createMiddleware({ type: 'function' })	带输入验证的函数级中间件
createStart() 中的 requestMiddleware	适用于所有请求（SSR、函数、路由）的全局中间件
createStart() 中的 functionMiddleware	仅适用于服务端函数的全局中间件
createIsomorphicFn()	为不同环境提供不同实现
createServerOnlyFn()	仅限服务端的工具——从客户端调用时会崩溃
createClientOnlyFn()	仅限客户端的工具——从服务端调用时会崩溃
useSession()	基于 Cookie 的会话，支持加密和安全设置
session.update()	更新会话数据
session.clear()	清除会话（登出）
beforeLoad	在路由加载前进行身份验证检查
_authenticated.tsx	用于分组保护的无路径布局路由
throw redirect({ to: '/login' })	重定向并附带返回 URL
await ensureQueryData()	关键数据会阻塞 SSR
prefetchQuery()	启动数据获取，不阻塞 SSR
<Suspense> 边界	定义流式传输分块
head: ({ loaderData }) => ({})	元标签、Open Graph、网站图标
head.scripts + JSON-LD	面向 LLMO 的结构化数据（schema.org）
llms.txt 服务端路由	AI 系统指南文件
headers: () => ({...})	在路由定义中设置 ISR／缓存控制
server: { handlers: { GET, POST } }	在 createFileRoute 上定义 API 路由
ssr: false	禁用特定路由的 SSR（SPA 模式）

执行边界

函数	运行位置	客户端可调用？	用途
createServerFn()	服务端	是（RPC 存根）	获取数据、修改数据
createServerOnlyFn()	服务端	否（会抛出错误）	密钥、数据库连接
createClientOnlyFn()	客户端	不适用	localStorage、DOM API
createIsomorphicFn()	两端	不适用	按环境提供不同实现

部署（Vite 插件）

平台	插件	运行时
Cloudflare	@cloudflare/vite-plugin	Workers
Netlify	@netlify/vite-plugin-tanstack-start	Node
Vercel	nitro/vite (preset: 'vercel')	Node
Node.js/Docker	nitro/vite (preset: 'node-server')	Node
AWS Lambda	nitro/vite (preset: 'aws-lambda')	Node
Bun	nitro/vite (preset: 'bun')	Bun
静态	nitro/vite (preset: 'static')	无

常见错误

错误	修正
服务端函数未使用 .inputValidator()	始终使用 Zod schema 进行验证
使用原生 fetch 而非 createServerFn	会失去类型安全、序列化和代码拆分能力
混用服务端和客户端代码，未划分边界	使用 createServerOnlyFn / createClientOnlyFn
在每个处理程序中检查身份验证	使用中间件组合或 beforeLoad
在 loader 中等待所有数据	只等待关键数据，其余数据提前获取
在渲染期间调用 Date.now()	从 loader 传入时间戳（会导致水合不匹配）
缺少 nodejs_compat 标志	Cloudflare 的 wrangler.toml 中必须设置
使用 GET 进行修改操作	创建、更新、删除操作使用 POST
未将 Cookie 转发到外部 API	使用 getRequestHeader() 或 createIsomorphicFn
在 loader 中使用 process.env（两端都会运行）	用 createServerFn 包装——loader 也会在客户端运行
服务端环境变量未验证	在 .server.ts 文件中使用 Zod 进行验证
将身份验证令牌存储在 localStorage 中	通过 useSession 使用 HTTP-only Cookie
向客户端暴露原始数据库错误	捕获错误并返回便于用户理解的消息，同时记录详细信息
内容页面缺少结构化数据	通过 head.scripts 添加 JSON-LD，便于 AI 发现

委派

使用此技能处理 TanStack Start 服务端函数、中间件、SSR/流式传输、路由保护、API 路由和部署配置。文件路由、搜索参数和数据加载模式请委派给 tanstack-router。缓存管理、乐观更新和查询模式请委派给 tanstack-query。

如果有 tanstack-form 技能，请将表单状态管理、验证和字段模式委派给它。 如果有 local-first 技能，请将本地优先架构决策和同步引擎选择委派给它。 如果有 electricsql 技能，请将 ElectricSQL shapes、身份验证配置和写入模式委派给它。 如果有 tanstack-db 技能，请将响应式集合、实时查询和乐观修改模式委派给它。

参考资料

• 服务端函数 — createServerFn、useServerFn、验证、身份验证、请求上下文、响应标头、文件上传、流式传输、TanStack Query 集成
• 中间件 — 组合、函数级中间件、路由级中间件、全局中间件、日志记录、速率限制
• SSR 与流式传输 — Suspense、预渲染、ISR、cache-control、混合策略、水合安全性
• 路由保护 — beforeLoad、无路径布局、会话安全、登录/登出、标头转发、Better Auth
• API 路由 — 服务端处理程序、REST 模式、路由级中间件、Webhook、健康检查、服务端函数与服务端路由
• 部署 — Vite 插件、适配器对比、Cloudflare D1/KV/R2 绑定、Docker、预渲染
• SEO 与 Head 管理 — head 属性、meta 标签、Open Graph、Twitter Cards、网站图标、SEO 助手
• LLM 优化（LLMO） — JSON-LD 结构化数据、schema.org、llms.txt、机器可读端点、AI 引用模式
• 错误处理 — 判别联合、自定义错误类、状态码、结果类型与 try-catch
• 文件组织 — 入口点、插件配置、执行边界、环境变量验证、.server.ts 约定
• 已知问题 — 10 个有解决方法的已记录问题
• Query 集成 — Router+Query 设置、SSR 集成、setupRouterSsrQueryIntegration、开发工具
• 集成流程 — 提交表单并更新缓存、无限滚动、分页表格、受身份验证保护的路由、错误处理
• Local-First 集成 — shape 代理服务端函数、混合使用基于服务端和 local-first 的数据、ElectricSQL 部署
• Electric 中间件 — shape 代理的身份验证中间件、全局中间件配置、sendContext、函数级验证