TanStack Start 是构建在 TanStack Router 与 Vite/Nitro 之上的全栈 React 框架,提供服务端函数、SSR、流式渲染和 API 路由,实现服务端到客户端的端到端类型安全。
用途与主要能力:用 createServerFn() 定义服务端逻辑(数据库访问、密钥、文件 I/O),配合 .validator() 校验输入、.handler() 处理请求;在路由 loader 中读取数据,在 useMutation 中写入;用 createAPIFileRoute 处理 webhook、OAuth 回调等原始 HTTP 端点;用 defer() 配合 Suspense 与 Await 流式渲染非关键数据。
使用方式:在 app.config.ts 中配置 Vite 插件与 server.preset(如 node-server、vercel、netlify、bun、cloudflare-pages);在 src/routes/__root.tsx 定义 HTML 外壳(html、head、body、Outlet、ScrollRestoration、Scripts);服务端函数建议放在 src/server/functions/ 或 *.server.ts;路由沿用 TanStack Router 的文件式路由、loader 与搜索参数校验。
限制与注意:服务端专属代码(密钥、数据库客户端、文件系统)只能放在服务端函数或 API 路由中,不可导入客户端组件;客户端环境变量需用 import.meta.env.VITE_*,服务端密钥仅在服务端函数内通过 process.env 读取;避免在 loader 中 await 全部数据而失去流式优势;不要跳过 .validator() 校验;Cloudflare Pages 需注意 Node API 兼容性差异。部署前需确认目标平台的 server.preset 与环境变量访问规则。