用途:TanStack Start 是一个构建于 TanStack Router 之上的全栈 React 框架,适合需要类型安全数据获取、服务端渲染与流式传输的 React 应用。当前处于 Release Candidate 阶段,API 在稳定 1.0 发布前仍可能变化。
主要能力:通过 createServerFn() 定义服务端函数,默认 GET 用于幂等可缓存的数据获取,createServerFn({ method: 'POST' }) 用于变更数据;可用 .inputValidator(zodSchema) 校验输入、.handler 编写带类型数据的服务端逻辑。支持 getRequest()、getRequestHeader()、setResponseHeaders()、useServerFn(),以及 createMiddleware().server(fn) 组合中间件并通过 next({ context: {} }) 向下游传数据。执行边界分为 createServerOnlyFn()、createClientOnlyFn()、createIsomorphicFn()。还提供基于 Cookie 加密的 useSession() 会话、beforeLoad 路由保护、head 元信息与 JSON-LD、ssr: false 的 SPA 模式,以及 createFileRoute 上的服务端 API 路由。
使用方式:主要围绕 createServerFn、createMiddleware、beforeLoad 等 API 组织代码,服务端函数需配合 Zod 输入校验。部署可通过 Vite 插件:Cloudflare 用 @cloudflare/vite-plugin,Netlify 用 @netlify/vite-plugin-tanstack-start,Vercel、Node、AWS Lambda、Bun、静态等使用 nitro/vite 对应 preset。Cloudflare 需在 wrangler.toml 中开启 nodejs_compat。
适用场景与限制:适合全栈 React 应用的数据获取、变更、鉴权、SSR/流式渲染与多平台部署。数据加载器在客户端也会运行,故 process.env 应包在 createServerFn 内;应避免在渲染中使用 Date.now() 以免hydration 不匹配;服务端环境变量需校验;鉴权令牌建议用 HTTP-only Cookie。具体问题与相应处理方式资料中列有 Known Issues 与常见错误表,此处不逐一展开。表单、路由、查询、本地优先等主题建议分别交由 tanstack-form、tanstack-router、tanstack-query、local-first 等相关技能处理。