服务器入口点（Server Entry Point）
注意
服务器入口点默认是可选的。如果未提供，TanStack Start 会用下面这份作为默认配置，自动为你处理服务器入口点。
服务器入口点（Server Entry Point）支持通用的 fetch handler 格式，这种格式被 Cloudflare Workers 和其他 WinterCG 兼容的运行时广泛使用。
为了确保互操作性，默认导出必须符合我们的 ServerEntry 接口：
export default {
fetch(req: Request, opts?: RequestOptions): Response | Promise<Response> {
// ...
},
}TanStack Start 提供了一个包装器，让创建过程类型安全。这是在 src/server.ts 文件中完成的。
// src/server.ts
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
export default createServerEntry({
fetch(request) {
return handler.fetch(request)
},
})无论我们是静态生成应用还是动态提供应用，server.ts 文件都是做所有 SSR 相关工作的入口点，也负责处理服务器路由和服务器函数的请求。
自定义服务器 handler
你可以创建自定义服务器 handler 来修改应用的渲染方式：
// src/server.ts
import {
createStartHandler,
defaultStreamHandler,
defineHandlerCallback,
} from '@tanstack/react-start/server'
import { createServerEntry } from '@tanstack/react-start/server-entry'
const customHandler = defineHandlerCallback((ctx) => {
// add custom logic here
return defaultStreamHandler(ctx)
})
const fetch = createStartHandler(customHandler)
export default createServerEntry({
fetch,
})请求上下文
当你的服务器需要把额外的、带类型的数据传进请求 handler 时（例如认证用户信息、数据库连接或按请求的标志位），可以通过 TypeScript 模块增强（module augmentation）注册一个请求上下文类型。注册的上下文会作为第二个参数传给服务器的 fetch handler，并在整个服务端中间件链中都可用——包括全局中间件、请求/函数中间件、服务器路由、服务器函数，以及路由器本身。
要为你的请求上下文添加类型，用 server.requestContext 属性增强 @tanstack/react-router 的 Register 接口。你传给 handler.fetch 的运行时 context 会与那个类型匹配。示例：
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
type MyRequestContext = {
hello: string
foo: number
}
declare module '@tanstack/react-router' {
interface Register {
server: {
requestContext: MyRequestContext
}
}
}
export default createServerEntry({
async fetch(request) {
return handler.fetch(request, { context: { hello: 'world', foo: 123 } })
},
})服务器配置
服务器入口点是你配置服务器专属行为的地方：
- 请求/响应中间件
- 自定义错误处理
- 认证逻辑
- 数据库连接
- 日志与监控
这种灵活性让你可以在保持框架约定的同时，定制 TanStack Start 应用处理服务端渲染的方式。
Cloudflare Workers
部署到 Cloudflare Workers 时，你可以扩展 server.ts 来处理更多 Workers 特性，比如队列、定时事件和 Durable Objects。完整指南请看 TanStack Start 的 Cloudflare Workers 文档。