用途
Cloudflare Durable Objects 是 Cloudflare Workers 平台上的有状态计算原语，用于构建实时应用、WebSocket 服务器、协调逻辑以及需要持久化状态的场景。该技能文档基于官方资料整理，状态标注为 Production Ready，最后更新于 2026-01-21，依赖 cloudflare-worker-base（推荐）。
主要能力
- 有状态对象：每个 Durable Object 实例拥有独立的持久化存储，可在请求之间保持状态。
- 两种存储后端：SQLite（推荐，10GB 存储、支持 SQL 查询、原子操作、PITR）与 KV（128MB，仅键值）。
- WebSocket 休眠 API：单实例支持数千个 WebSocket 连接，空闲约 10 秒后休眠以节省成本，消息到达时自动唤醒。2025 年 10 月消息大小上限从 1 MiB 提升至 32 MiB。
- Alarms API：可安排对象在未来时间唤醒，用于批处理、清理、提醒、周期任务；至少一次执行，自动重试（最多 6 次，指数退避），成功后自动删除。
- RPC 与 HTTP Fetch：RPC 为推荐方式，直接方法调用、类型安全；HTTP Fetch 用于 WebSocket 升级或复杂路由。
- ID 与路由：idFromName（一致路由）、newUniqueId（随机唯一 ID）、idFromString（从保存的 ID 重建）；支持位置提示（best-effort）与司法管辖区（eu、fedramp，严格强制）。
- 迁移（Migrations）：用于创建、重命名、删除、转移 DO 类；原子执行，标签唯一且仅追加。
使用方式
脚手架创建新项目：
npm create cloudflare@latest my-durable-app -- --template=cloudflare/durable-objects-template --ts
定义 DO 类需从 cloudflare:workers 导入 DurableObject，构造函数首行调用 super(ctx, env)，并导出该类（export default MyDO;），Worker 也需导出 DO 类。配置在 wrangler.jsonc 中声明 durable_objects.bindings 与 migrations，新 DO 使用 new_sqlite_classes。
存储操作：KV API 提供 put/get/delete、批量操作、list、deleteAll 与 transaction；SQL API 提供 sql.exec、cursor.one、cursor.toArray、transactionSync，建议使用 ? 占位符、创建索引、使用 PRAGMA optimize、添加 STRICT 关键字、将布尔值转为整数。
WebSocket 休眠需使用 ctx.acceptWebSocket(server)（而非 ws.accept()），用 serializeAttachment() 持久化每个连接的元数据，并在构造函数中通过 ctx.getWebSockets().forEach() 恢复。禁止使用 setTimeout/setInterval，应改用 alarms。
适用场景
实时应用、WebSocket 服务器、聊天室、用户会话、按租户逻辑、单例协调、限流、带 TTL 的会话管理、领导者选举、多 DO 协调等。
限制
- 迁移为原子操作，无法渐进式发布；标签唯一且仅追加。
- 无法在已有 KV 后端的 DO 上启用 SQLite，需新建 DO 类。
- 每个 DO 仅一个 alarm，新 alarm 会覆盖旧的。
- 位置提示仅为 best-effort，不保证生效；司法管辖区不能与位置提示组合使用，辖区外延迟更高。
- 休眠会清除内存状态，WebSocket 场景必须持久化关键状态。
- 构造函数应保持精简，繁重工作会阻塞休眠唤醒。
- 类名在账户内全局唯一。
- 2025 年 6 月推出的 @cloudflare/actors 库仍为 beta，存在 RPC 序列化、vitest 集成、内存管理等已知问题，生产使用前需查看活跃 issue。
已知问题预防
该技能汇总了 20 个已记录错误的预防方法，包括：类未导出、缺少迁移、构造函数未调用 super、使用 setTimeout/setInterval、仅依赖内存状态、对已有 KV DO 启用 SQLite、使用标准 WebSocket API 期望休眠、假设位置提示有保证等。