用途:当任务聚焦用户身份、会话处理、受保护流程,或需决定后端与数据库逻辑在 TanStack Start 应用中应放在何处时,使用本技能。路由线索包括 Clerk、WorkOS、Better Auth、Auth.js、DIY auth、登录/登出、会话 cookie、beforeLoad 保护、useSession,以及在 server functions 与 loaders 中访问数据库。若问题是一般 server-function 机制、中间件顺序或 src/server.ts 管道,应改用 tanstack-start-server-runtime-and-apis;模板选择、Tailwind 配置或 Start 与 Next.js 的高层取舍属于 tanstack-start-overview-and-setup;托管商配置或生产可观测性属于 tanstack-start-deployment-and-runtime-ops。
工作流:先读 references/auth-backend-and-data-access.md;在写路由守卫前先确定认证模型(托管服务、开源库或自建会话);敏感逻辑应放在 server functions、中间件或 server routes,而非仅客户端状态;数据库访问靠近服务端边界,只把所需数据传给路由组件。
示例:使用 createFileRoute 与 beforeLoad,在其中调用 getCurrentUserFn(),未登录时 throw redirect 到 /login 并携带 redirect 查询参数,返回 { user } 作为路由上下文。
注意:官方文档要求有意识地选择认证方案,托管方案与自建方案在所有权和安全权衡上不同;TanStack Start 提供原语,但不替代安全设计;会话 cookie 应保持 HTTP-only 并由服务端管理;路由保护应放在 beforeLoad、中间件或服务端边界,而非仅客户端组件检查;已有服务端状态时,数据库访问不应塞进临时的客户端 fetch 逻辑。
维护快照:2026-03-24;@tanstack/react-start@1.167.2 于 2026-03-21 发布;官方文档仍标注为 RC/功能完整,建议生产环境锁定版本。