用途:帮助理解 TanStack Start 中代码究竟在哪里运行。默认所有代码都是同构的,会同时进入服务端与客户端打包;路由 loader 在 SSR 与客户端导航时都会执行,因此服务端专属操作必须使用 createServerFn。
主要能力:createServerFn 用于 RPC 与数据变更,客户端调用会变成网络请求;createServerOnlyFn 在客户端调用时抛错;createClientOnlyFn 在服务端抛错;createIsomorphicFn 可为不同环境提供 .client() 与 .server() 实现;<ClientOnly> 与 useHydrated() 处理仅浏览器渲染与 hydration 相关逻辑。文件级保护可用 .server.* / .client.* 后缀,或导入 '@tanstack/react-start/server-only'、'@tanstack/react-start/client-only' 等标记(实验性)。
用法要点:环境变量在 createServerFn 的 handler 内通过 process.env 读取,不要在模块顶层读取;客户端只能访问 VITE_ 前缀变量,服务端密钥不得加 VITE_ 前缀。同构 loader 中避免相对 URL 的 fetch,应调用服务端函数或放入明确的环境边界。
适用场景:需要区分服务端与客户端逻辑的 TanStack Start 应用,包括数据库访问、密钥使用、浏览器 API、分析脚本与 hydration 处理。
限制:文件标记为实验性,生产构建默认报错、开发环境返回递归 Proxy 模拟;同一文件同时使用两种标记会报错;类型导入被忽略。具体部署目标对执行的影响暂未提供更多细节。