用途:Server Routes 是在应用路由旁定义的 API 端点,放在 src/routes 目录中,使用 createFileRoute 的 server 属性处理原始 HTTP 请求。
主要能力:支持 GET、POST、PUT、DELETE 等 HTTP 方法处理器;同一文件可同时定义服务端路由与 UI 路由;遵循基于文件的路由约定,支持动态路径参数(如 $id)与通配参数($,通过 params._splat 获取);可读取请求体(request.json()、request.text()、request.formData()),可用 Response.json 返回 JSON,并设置状态码与响应头。
处理器上下文:每个处理器接收 request、params(动态路径参数)、context(中间件上下文)、pathname(匹配路径)与 next(回退到 SSR 的调用,返回 Response)。
中间件:可在 server.middleware 中为所有处理器统一添加;也可使用 createHandlers 为特定方法单独配置中间件与处理器,路由级与处理器级中间件可组合,路由级先执行。
限制与注意:每个路由只能有一个处理器文件,重复路径(如 users.ts 与 users/index.ts 同时存在)会冲突;读取请求体方法必须 await,否则拿到的是 Promise 而非数据。
相关功能:中间件(start-core/middleware)与 Server Functions(start-core/server-functions,用于 RPC 风格调用)可作为替代方案。