Cloudflare 持久化对象

要解决什么问题

在 Cloudflare Workers 上跑无状态请求很简单，但一旦涉及聊天室、库存扣减、按用户隔离的数据或长连接 WebSocket，就需要单实例上的强一致与协调。Durable Objects（DO）是 Cloudflare 提供的「每个逻辑实体一个可持久化实例」的边缘运行时模型；若仍按普通 Worker 思路设计，很容易出现全局单 DO 瓶颈、blockConcurrencyWhile 误用导致吞吐崩溃，或状态只放内存而在驱逐后丢失。

技能如何帮你落地

本技能强调 Prefer retrieval over pre-training：实现前先查 官方文档 与 API，并配合仓库内 ./references/rules.md、testing.md、workers.md 等规则摘要。核心能力包括：

• 何时用 DO：协调（房间/协作）、强一致（库存/预订）、按实体存储（多租户）、WebSocket、按实体定时任务（setAlarm）
• Wrangler 与迁移：在 wrangler.jsonc/toml 中配置 DO binding，新项目用 SQLite 存储（new_sqlite_classes）
• 实例路由：用 getByName() / idFromName 做确定性分片，按「协调原子」建模（一房间/一用户/一游戏一局一个 DO，而非一个全局 DO）
• RPC 与生命周期：兼容日期 ≥ 2024-04-03 时优先 RPC 方法而非仅靠 fetch()；构造里用 blockConcurrencyWhile() 仅做 schema 初始化
• 存储纪律：先持久化再改内存；相关写入避免在中间插入无关 await 以免破坏原子性；每个 DO 仅保留一个 alarm（新 setAlarm 会替换旧的）
• 测试：用 @cloudflare/vitest-pool-workers 做单元/集成与 alarm 测试

适用边界与注意点

不适合纯无状态转发、追求极致全球扇出且彼此独立的请求，或可以把状态完全交给外部数据库且无需边缘协调的场景——这类应继续用普通 Workers。

明确反模式：单个全局 DO 扛全部流量、每次请求都 blockConcurrencyWhile()、关键状态只存内存、在 blockConcurrencyWhile 内做外部 I/O 或跨 fetch。设计分片与父子 DO 关系时，应围绕业务上的协调单元，而不是「把所有状态塞进一个对象」。