用途:该技能面向 TanStack Start(@tanstack/react-start v1.168.58)的执行模型问题,帮助判断代码在服务端、客户端还是两端运行,并修复密钥泄露、在路由 loader 中直接访问数据库、水合不一致等常见错误。
主要能力:说明 Start 中所有模块默认同构,同时进入服务端与客户端打包,路由 loader 在 SSR 与客户端导航时都会执行,因此数据库、文件系统与密钥必须放在 createServerFn 或 createServerOnlyFn 内部,不能出现在裸 loader 或模块作用域。强调 process.env 必须按请求读取而非模块作用域读取,因为模块级读取可能被内联进客户端打包导致泄露,且在按请求注入环境变量的边缘运行时上为 undefined;VITE_/PUBLIC_ 前缀变量会暴露给客户端,服务端密钥不得带此类前缀。文档化了各环境边界 API:createServerFn、createServerOnlyFn、createClientOnlyFn、createIsomorphicFn、ClientOnly、useHydrated(),以及仅服务端/仅客户端导入标记,并给出选择框架与可复制的边界示例。
使用方式:这些边界创建器从 @tanstack/react-start 导入,ClientOnly 与 useHydrated 来自 @tanstack/react-router。写边界代码前需对照 Context7 与 Exa 验证 API,改动后运行 fuse-ai-pilot:sniper。选择框架为:仅服务端用于密钥、数据库、文件系统、外部 API key;仅客户端用于 DOM、localStorage、定位、分析;同构用于格式化、业务逻辑、共享工具与 loader。
适用场景与限制:适用于决定代码运行位置、修复泄露与同构 bug;不适用于初始项目搭建(用 start-core)或文件目录的 SOLID 组织(用 solid-tanstack-start)。禁止事项包括在裸 loader 中访问数据库/密钥/文件系统、模块作用域读取 process.env、给密钥加 VITE_/PUBLIC_ 前缀、直接输出 new Date() 等非确定性渲染内容导致水合不一致,以及动态 import() 一个 *.functions.ts 服务端函数。