用途:TanStack Start 的服务端运行时,提供请求处理器、请求/响应工具、Cookie 管理、会话管理与查询校验。所有工具基于 AsyncLocalStorage,可在请求调用栈任意位置使用,无需传参。
主要能力:createStartHandler 创建主请求处理器,按三阶段处理请求——服务端函数分发(/_serverFn 前缀)、服务端路由处理器、应用 SSR(如 defaultStreamHandler),并支持 transformAssets 做 CDN 资源 URL 转换。请求工具含 getRequest、getRequestHeaders、getRequestHeader、getRequestIP、getRequestHost、getRequestUrl、getRequestProtocol;响应工具含 setResponseHeader(s)、setResponseStatus、getResponseHeader(s)、getResponseStatus、removeResponseHeader、clearResponseHeaders;Cookie 含 getCookies、getCookie、setCookie、deleteCookie;会话含 useSession、getSession、updateSession、clearSession,会话数据加密存于 Cookie,需 password(至少 32 字符),可配置 name、maxAge、cookie;getValidatedQuery 接受 Standard Schema 校验器(非回调)校验查询参数。
使用方式:从 @tanstack/<framework>-start/server 导入(react、solid、vue),在 createServerFn 或中间件内调用。类型完全推断,不要强制转换或标注。
限制与注意:这些工具仅限服务端,客户端导入会构建报错或运行时崩溃;除 clearSession 外多数会话操作必须提供 password;生产环境会话 Cookie 应设 secure、HttpOnly、SameSite、Path=/;不要在模块作用域捕获请求或环境状态,应在处理器内读取,避免并发请求共享状态与边缘运行时问题。会话数据应小且非敏感,需要撤销、设备跟踪或即时角色变更时改用服务端会话记录,仅存不透明 ID,并在登录、权限变更、改密、登出后轮换会话。