用途:Cloudflare Durable Objects 是全局唯一的有状态对象,用于单点协调、强一致事务存储、实时通信与持久状态。适用于聊天室、实时协作、多人游戏服务器、限流与会话管理、领导者选举、带休眠的 WebSocket 服务、有状态工作流与队列、按用户或房间的逻辑。
主要能力:每个实例全局唯一并自动路由到最优位置,提供可串行化 ACID 存储;内置 SQLite 数据库(上限 1GB)或键值存储(KV 后端上限 128MB);WebSocket 休眠 API 支持每实例数千连接并在空闲时休眠;Alarms API 执行定时任务;可自动扩展到数百万独立实例。
使用方式:可用 npm create cloudflare@latest my-durable-app -- --template=cloudflare/durable-objects-template --ts --git --deploy false 创建项目,或在现有 Worker 中安装 @cloudflare/workers-types。Durable Object 类必须继承 cloudflare:workers 的 DurableObject,构造函数先调用 super(ctx, env),并导出该类。在 wrangler.jsonc 中配置 durable_objects.bindings 与 migrations(新类用 new_sqlite_classes 启用 SQLite 后端),Worker 通过 env.BINDING.idFromName() 获取 stub 并调用 RPC 方法,最后用 npx wrangler deploy 部署。存储可用 ctx.storage.sql 执行参数化 SQL,或用 ctx.storage 的 get/put/delete/list 键值 API。WebSocket 必须用 ctx.acceptWebSocket() 启用休眠,并用 serializeAttachment() 持久化每连接元数据,在构造函数中通过 getWebSockets() 恢复。
限制:休眠时内存状态会丢失,需持久化;禁止使用 setTimeout/setInterval,应改用 Alarms;已部署的 KV 后端 DO 不支持启用 SQLite;不要访问内部 __cf_kv 表。资料未提供收费与价格信息。