该资料聚焦 Cloudflare Durable Objects,用于在边缘构建有状态、可协调的应用,并明确推荐新项目采用 SQLite 后端(通过 migrations 中的 new_sqlite_classes 配置)。适用场景包括:为有状态协调创建新的 Durable Object 类、实现 RPC 方法/报警/WebSocket 处理器、审查既有代码、配置 wrangler 绑定与迁移、用 @cloudflare/vitest-pool-workers 编写测试,以及设计分片策略与父子关系。
核心能力与用法:每个 Durable Object 实例单线程串行处理请求,请求自动排队;输入门在存储操作期间阻塞新事件以避免竞态,输出门在写入确认前扣留响应以保证持久性;相关写入不加 await 可自动合并为原子提交。存储提供 ctx.storage.sql(结构化 SQLite)、同步 KV ctx.storage.kv 与旧异步 KV;事务推荐 transactionSync,并明确不要在 SQL 中手写 BEGIN/COMMIT/ROLLBACK。另支持 Point-in-Time Recovery(30 天内恢复,同时覆盖 SQL 与 KV)、alarms 定时任务,以及可休眠的 WebSocket(须用 this.ctx.acceptWebSocket(server),不用 addEventListener)。
路由建议用 getByName() 获得确定性实例,配合 RPC 方法而非 fetch() 更类型安全。限制与注意事项:不要建全局单例 DO(约 1k 请求/秒瓶颈),应按用户/房间/游戏分片;避免每次请求都用 blockConcurrencyWhile();不要把关键状态只存内存;过载时返回 429 并退避重试;每个 DO 仅一个 alarm。更多细节见其引用文档。