TanStack Start - 服务端入口点 (Server Entry Point)

配置服务端处理程序、自定义请求处理和类型安全的请求上下文。服务端入口点在默认情况下是可选的，如果未提供，TanStack Start 将自动处理。

概述

服务端入口点支持通用的 fetch 处理程序格式，通常由 Cloudflare Workers 和其他与 WinterCG 兼容的运行时使用。默认导出必须符合 ServerEntry 接口：

export default {
  fetch(req: Request, opts?: RequestOptions): Response | Promise<Response> {
    // ...
  },
}

基本设置

TanStack Start 公开了一个包装器使创建类型安全，在 src/server.ts 文件中完成：

tsx

// src/server.ts
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'

export default createServerEntry({
  fetch(request) {
    return handler.fetch(request)
  },
})

无论是静态生成应用还是动态服务应用，server.ts 文件都是以下内容的入口点：

所有 SSR 相关工作
处理服务端路由
处理服务端函数请求

自定义服务端处理程序

tsx

// src/server.ts
import {
  createStartHandler,
  defaultStreamHandler,
  defineHandlerCallback,
} from '@tanstack/react-start/server'
import { createServerEntry } from '@tanstack/react-start/server-entry'

const customHandler = defineHandlerCallback((ctx) => {
  // 自定义请求处理
  console.log('Request:', ctx.request.url)
  const startTime = Date.now()
  const result = defaultStreamHandler(ctx)
  console.log(`Request processed in ${Date.now() - startTime}ms`)
  return result
})

const fetch = createStartHandler(customHandler)

export default createServerEntry({
  fetch,
})

请求上下文

当服务端需要将额外的类型化数据传递到请求处理程序时，通过 TypeScript 模块增强注册请求上下文类型：

tsx

// src/server.ts
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'

type MyRequestContext = {
  hello: string
  foo: number
}

declare module '@tanstack/react-start' {
  interface Register {
    server: {
      requestContext: MyRequestContext
    }
  }
}

export default createServerEntry({
  async fetch(request) {
    return handler.fetch(request, {
      context: {
        hello: 'world',
        foo: 123
      }
    })
  },
})

在中间件中使用上下文：

tsx

const myMiddleware = createMiddleware().server(async ({ next, context }) => {
  console.log(context.hello) // 'world'
  console.log(context.foo)   // 123
  return next()
})

完整示例

tsx

// src/server.ts
type RequestContext = {
  user?: { id: string; email: string }
  db: Database
}

declare module '@tanstack/react-start' {
  interface Register {
    server: {
      requestContext: RequestContext
    }
  }
}

const customHandler = defineHandlerCallback(async (ctx) => {
  const user = await getUserFromRequest(ctx.request)
  const db = await getDatabaseConnection()
  return defaultStreamHandler({
    ...ctx,
    context: { user, db },
  })
})

export default createServerEntry({
  fetch: createStartHandler(customHandler),
})

WinterCG 兼容性

服务端入口点的 fetch 处理程序格式与以下运行时兼容：

Cloudflare Workers
Deno
Bun
Node.js (通过 wintercg)
Fastly

API 速查

API	用途
`createServerEntry()`	创建服务端入口点
`createStartHandler()`	创建启动处理程序
`defaultStreamHandler()`	默认流处理程序
`defineHandlerCallback()`	定义处理程序回调

请求上下文流程

text

Request
    │
    ▼
server.ts (fetch)
    │
    ├─ 提取用户信息
    ├─ 创建数据库连接
    └─ 创建上下文
         │
         ▼
    Middleware Chain
         │
         ├─ 全局中间件
         ├─ 请求中间件
         └─ 函数中间件
              │
              ▼
    Handlers
         │
         ├─ 服务端路由
         └─ 服务端函数