TL;DR： Durable Objects 是采用单实例模式的 JavaScript 类，它能够跨请求维持状态并处理集群协调。与无状态的 Workers 截然不同，Durable Objects 提供了全局唯一性保证——针对特定 ID，其在全球网络中仅会存在一个独立的活跃实例。本指南将全面讲解核心用例（包括 WebSocket 房间模块、全局速率限制与分布式计数器），探索基于持久化特性的生命周期工作机制，并分享其在 TanStack Start 中落地集成的工程实践。如需获取在 Workers 中关于 WebSocket 连接配置的更多剖析，请查阅我们的 Cloudflare Workers WebSocket 指南。完整指南请访问 tanstackship.com。
简介
Workers 在架构设计初衷上是无状态的。因此每一个请求都可能会流向不同的数据中心。然而在面临需要处理跨端协调机制的应用体系中——例如互动聊天室、深度协同文档工具或多端分布式原子计数器——您需要一个充当唯一协调源的单点。Durable Objects 以提供具有全局唯一定位的状态实例的形式，精准地解决了这一痛点挑战。如果您之前未曾开发体验过 Workers 系统，建议您优先参阅 Cloudflare Workers 入门介绍，该文档将为您理解 DO 架构原理直接铺设必需的基础认知。
基础 Durable Object
export class ChatRoom implements DurableObject {
private sessions: Map<string, WebSocket> = new Map()
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url)
if (url.pathname === '/websocket') {
const pair = new WebSocketPair()
const [client, server] = Object.values(pair)
this.sessions.set(crypto.randomUUID(), server)
server.accept()
server.addEventListener('message', (event) => {
// 广播给所有已连接的客户端
this.sessions.forEach((ws) => {
ws.send(event.data as string)
})
})
return new Response(null, { status: 101, webSocket: client })
}
return new Response('Not found', { status: 404 })
}
}
Durable Object 典型用例
| 用例 | 对象专属状态 | 协调模式 |
|---|---|---|
| 聊天室 | 已连接的 WebSockets | 广播至所有客户端 |
| 速率限制器 | 请求计数器 | 达到设定的阈值时拒绝 |
| 游戏大厅 | 玩家列表 | 对战玩家系统匹配 |
| 文档同步 | 操作日志 | CRDT/OT 合并 |
| 分布式计数器 | 计数器数值 | 全局执行原子递增 |
总结
Durable Objects 完美地填补了相对无状态特性的基础 Workers 与传统中心化数据库之间的架构鸿沟。它们具备出色敏捷地针对各类实时通信应用去提供带有单实例特质的核心组件节点管理支撑能力。当您的整体后端系统构建面临着强制的全局唯一性保证或者是强健的数据事务性留存机制等核心限制需求时，优先将其作为绝对的首选方案。
有关应用全流程的具体细节演练范例教程，请参阅构建实时聊天应用的教程。如果要将这些高频流动的业务实时数据成功连接并推向前端内部状态系统中去，TanStack Query WebSocket 集成方案 将为您展示出如何使得前端界面 UI 毫不费力地与具有快速响应要求的直播数据帧保持即时同步运转。