用途:说明 TanStack Start 的执行模型,帮助判断代码运行在服务端还是客户端。核心前提是所有代码默认同构,路由 loader 在 SSR 与客户端导航时都会执行,服务端专属操作必须使用 createServerFn。
主要能力:提供环境边界 API 一览——createServerFn() 用于 RPC 与数据变更,客户端发起网络请求、服务端直接执行;createServerOnlyFn(fn) 在客户端抛错;createClientOnlyFn(fn) 在服务端抛错;createIsomorphicFn() 按环境选择 .client() 或 .server() 实现;<ClientOnly> 与 useHydrated() 处理仅浏览器内容与注水逻辑。还支持用文件标记限制导入,如导入 '@tanstack/react-start/server-only' 或 client-only,或采用 .server.、.client. 文件名后缀(实验性)。
必要用法:服务端读取环境变量应放在 .handler() 等按请求执行的函数内,不能在模块顶层读 process.env;客户端仅能访问带 VITE_ 前缀的变量,服务端密钥不得加该前缀。若需把服务端变量传给客户端,可通过 createServerFn 返回。可用 env.d.ts 为 import.meta.env 与 process.env 补充类型。
适用场景与限制:适合需要区分环境的数据逻辑、敏感信息、数据库与文件系统访问,以及浏览器 API、localStorage、埋点等客户端专属逻辑。注意 loader 并非服务端专属,误用会泄露密钥;边缘运行时下模块级 env 读取会得到 undefined;VITE_ 前缀变量会暴露给客户端;同构不一致会导致注水不匹配。同一文件不能同时使用 server-only 与 client-only 标记。具体部署与版本差异资料未提供。