TanStack Router 服务端安全指南Server Functions、中间件、CSRF防护与认证配置完整教程【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/routerTanStack Router含 TanStack Start 全栈框架是一个客户端优先、服务端能力完备、全链路类型安全的 Web 路由与框架。本文带你零基础掌握它的服务端安全四件套Server Functions服务端函数、中间件Middleware、CSRF 防护与认证Session Cookie配置帮你把数据安全边界一次搭对。为什么新手最该先懂服务端安全边界很多教程教你怎么登录却没告诉你数据怎么防偷。在 TanStack Start 中安全的核心思想只有一句️路由守卫beforeLoad只负责用户体验真正的安全边界在数据端点本身。Server Functions 和 Server Routes 本质上是独立可达的 API 端点——即使你前端跳转了登录页攻击者仍可能直接调用接口。所以官方文档明确要求每个读写私有数据的端点都要在处理器或中间件里自己做鉴权。Server Functions自带安全外壳的服务端函数Server Functions 让你在客户端像调用本地函数一样调用服务器代码数据库访问、环境变量、文件系统等敏感能力全部留在服务端跨网络边界的输入输出还会被 TypeScript 强制做可序列化检查strict 模式从类型层面堵住隐患。文件命名约定 天然隔离机制官方推荐用文件名后缀区分安全等级构建期会自动把服务端实现从浏览器包里摇树掉文件名后缀用途能否被客户端导入.functions.tscreateServerFn封装层✅ 安全构建后变 RPC 桩.server.ts纯服务端逻辑DB 查询等❌ 仅在函数内部引入无后缀.ts类型、Schema 等共享代码✅输入校验网络边界上的第一道闸Server Functions 与网络之间必须做校验官方建议直接挂 Zod 之类的 Schema 库适配器位于 packages/zod-adapter/。输入不合法就在入口被拒永远不要把未校验的data交给业务逻辑。CSRF 防护默认开启自定义后需手动装回Server Functions 是同源 RPC 端点因此 TanStack Start 内置了createCsrfMiddleware()通过校验Sec-Fetch-Site、Origin、Referer请求头来拒绝跨站伪造请求默认行为没有src/start.ts时框架自动为所有 Server Functions 安装 CSRF 中间件新手零配置即受保护自定义后一旦你创建了自己的src/start.ts就要显式装回它// src/start.ts import { createStart, createCsrfMiddleware } from tanstack/react-start const csrfMiddleware createCsrfMiddleware({ filter: (ctx) ctx.handlerType serverFn, }) export const startInstance createStart(() ({ requestMiddleware: [csrfMiddleware], }))两个实用细节如果部署在子域名/独立域名下可用origin选项指定公网源createCsrfMiddleware({ origin: https://app.example.com })若自定义了src/start.ts却没装 CSRF 中间件开发模式会对 Server Function 请求给出警告——别忽略它也别急着关掉。完整原理见 server-functions.md 与 middleware.md。中间件把鉴权、限流变成可组合的安检门TanStack Start 的中间件分两类覆盖不同颗粒度类型作用范围能力请求中间件createMiddleware()所有服务端请求含 SSR、Server Routes、Server Fns全局鉴权、日志、CSP、监控函数中间件{ type: function }仅 Server Functions额外支持.validator()输入改写、.client()客户端侧逻辑认证中间件的推荐写法把读取 Session → 校验 → 注入 context封装成一个authMiddleware然后挂到每一个涉及私有数据的 Server Function 上。这是官方反复强调的模式见 authentication-server-primitives.md。两个容易踩的坑客户端上下文sendContext≠ 可信数据客户端发的任何值都可能被篡改必须在服务端中间件里重新校验更关键的——形状合法不等于有权限拿到workspaceId还要验证当前会话用户是否真是该空间成员否则登录用户可改写参数遍历他人数据。限流中间件登录、改密这类凭据端点必须做 IP/账户维度的频率限制否则就是撞库的靶子。官方在认证服务端原语文档中给出了rateLimitMiddleware的完整形态。认证配置Session、Cookie 与路由保护的三层结构第一层会话存储框架提供基于useSession()的HTTP-only Cookie 会话密码至少 32 字符。若手写 Cookie如__Host-session前缀务必记住这组安全旗标旗标防什么HttpOnlyXSS 无法用 JS 偷走会话Secure仅限 HTTPS 传输SameSiteLax拦截绝大多数跨站 POST 伪造__Host-前缀绑定精确源防子域劫持的会话固定攻击Max-Age 服务端轮换会话可主动吊销第二层路由保护UX 层用布局路由 beforeLoad拦截未登录访问并redirect到登录页根路由在beforeLoad里调用getCurrentUserFn()让首次渲染与子路由共享同一份登录态登录/登出后调用router.invalidate()刷新全局状态。第三层会话轮换进阶必做登录、改密、提权时销毁旧会话、签发新会话可一举废掉会话固定攻击。官方认证文档authentication.md还覆盖了登录防用户枚举统一错误文案 假哈希比对消除时间差、OAuthstate PKCE、密码重置防枚举等生产级细节。上线前安全自检清单对照 production-checklist.md 做五项关键验证✅直连测试未登录、换账号分别直接调用私有读写端点必须全部拒绝✅双账号并发请求同一私有 URL每份响应只能包含自己的数据验证缓存隔离✅会话过期与登出旧账号数据不得残留在浏览器缓存中✅跨站写请求用不可信源模拟浏览器 POST确认校验先于任何写操作生效✅密钥不外泄用无害测试密钥构建搜索客户端产物与响应体确认无泄漏。小结能力一句话要点Server Functions服务端逻辑的安全外壳输入必校验、静态导入安全CSRF 防护默认自动装自定义src/start.ts后记得手动装回中间件鉴权挂端点而非路由客户端传来的数据一律再校验认证配置Cookie 安全旗标 beforeLoadUX 守卫 会话轮换延伸阅读Server Functions 指南 · 中间件指南 · 认证服务端原语 · 完整认证示例 e2e/react-start/basic-auth/【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考