---
id: start.middleware-chain
kind: contract
product: start
framework: react
locale: zh-CN
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "^1"
verifiedAgainst: "@tanstack/react-start@1.168.34"
contentModel: 2
packages:
  - "@tanstack/react-start"
tasks:
  - "create-middleware"
  - "compose-server-function-middleware"
  - "choose-middleware-scope"
sourceRefs:
  - "https://tanstack.com/start/latest/docs/framework/react/guide/middleware"
  - "https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"
---

# 建立 Start Middleware 执行链

> 明确请求级与函数级作用域，通过 next() 组合上下文，并保留认证和 CSRF 边界。

## 执行契约

- **适用场景:** 多个 Server Function、Server Route 或请求需要共享日志、认证、Context 或计时逻辑。
- **不要使用:** 只服务一个处理器且没有复用价值的业务逻辑应留在处理器或领域服务中。
- **前置检查:** 确定 Middleware 类型、执行顺序、Context 输入输出以及 next() 的错误传播方式。
- **验证结果:** 测试顺序、短路、错误和并发请求，确认每个请求的 Context 相互隔离。
- **失败模式:** 处理器未执行或 Context 丢失通常是 next() 未返回、顺序错误或 Middleware 类型不匹配。
- **安全边界:** 日志 Middleware 应主动移除 cookie、Authorization、秘密和敏感请求体。

## 作用域契约

createMiddleware() 默认创建请求中间件，可覆盖 SSR、Server Route 和 Server Function。createMiddleware({ type: 'function' }) 创建 Server Function 中间件，可使用 validator 和 client 阶段。不要为了复用而把局部函数规则提升成全局请求规则。

## 链路实现

调用 next 执行下游并返回其结果。通过 next({ context }) 添加的字段只能向下游传播；如果中间件提前返回，应当是有意定义的拒绝或响应，而不是遗漏 next。

File: `src/server/request-context.ts`

```ts
import { createMiddleware } from '@tanstack/react-start'

export const requestIdMiddleware = createMiddleware()
  .server(({ next }) => next({
    context: { requestId: crypto.randomUUID() },
  }))
```

## 安全不变量

客户端 sendContext 是不可信输入，必须在服务端验证，且不能提供身份本身。自定义 src/start.ts 后要显式保留 createCsrfMiddleware；CSRF、输入校验、认证和资源级授权是不同检查。

## Official sources

- https://tanstack.com/start/latest/docs/framework/react/guide/middleware
- https://tanstack.com/start/latest/docs/framework/react/guide/server-functions