cloudflare-durable-objects 快速入门

把”边缘计算 + 状态持久化”做成像写普通对象一样自然,让实时协作 / WebSocket 应用不再难。

这是什么?解决什么问题?

Serverless(无服务器)最大的痛点是什么?——没有状态。云函数每次启动都是干净的,想做 WebSocket 聊天、在线协作、实时游戏、计数器,都要外挂 Redis 或数据库,延迟和复杂度都上去了。

Cloudflare Durable Objects(DO)是 Cloudflare Workers 平台上的一种特殊对象,它把”计算 + 状态 + 网络”绑在一起:每个 DO 实例有自己独立的 SQLite 存储,有唯一 ID,可以在边缘节点就近响应,支持 WebSocket 长连接。简单说,你可以把 DO 理解为”全球分布的、状态自包含的微型服务”。

cloudflare-durable-objects Skill 是社区维护的最佳实践合集,价值在于:把 DO 开发里那些”文档不写但线上一定踩”的坑(20+ 已知 bug、SQLite 迁移、hibernation API、跨区域一致性)整理成可被 AI 调用的知识库。AI 在帮你写 DO 代码时,会主动提示”这里要 catch 哪些异常”、“hibernation 必须先 setWebSocketAutoResponse”等关键细节。

适合:做实时协作白板、多人在线游戏、即时聊天、分布式计数器、限流器、跨区域分布式锁等场景的工程师。

准备工作

1. Node.js 18+ 或 Wrangler CLI
2. Cloudflare 账号:免费版每天 10 万次请求,https://dash.cloudflare.com/sign-up
3. Wrangler CLI:Workers 官方工具,npm install -g wrangler
4. 可选:miniflare 本地模拟器,调试用

3 步快速上手

第 1 步:安装 Skill

npx skills add cloudflare/skills --skill cloudflare-durable-objects

仓库:https://github.com/cloudflare/skills

第 2 步:创建 Worker 项目

npm create cloudflare@latest my-do-app -- --template worker-durable-object
cd my-do-app
npx wrangler login

第 3 步:用 Skill 写一个计数器

对 AI 说:

用 cloudflare-durable-objects Skill,写一个 Worker + DO,
GET /counter/:id 增加并返回当前计数,数据用 SQLite 存储

AI 会输出 src/index.ts,包含 DurableObject 类、increment() 方法、env.DB 绑定等关键代码。运行 npx wrangler dev 启动,curl http://localhost:8787/counter/abc 即可看到数字递增。

常见踩坑

1. WebSocket Hibernation 没用:开了 DO 但没用 Hibernation API,长连接空闲时仍按请求计费,账单爆炸。this.ctx.acceptWebSocket(server) + webSocketMessage 事件是正确姿势。
2. SQLite 写并发阻塞:DO 的 SQLite 是单写多读,大量并发写会卡住。务必用 blockConcurrencyWhile 包装写操作,或者合并写入。
3. 跨区域 ID 路由:DO 默认按 ID 哈希路由到固定区域,如果你用了 locationHint 但 ID 没带地理前缀,会出现”用户 A 写入、用户 B 读不到”的情况。
4. 本地开发与生产不一致:wrangler dev 用的 SQLite 是内存版的,某些边界行为(并发、断电恢复)和生产不一致,关键路径要在 wrangler dev --remote 上跑。
5. Eviction(驱逐)与持久化矛盾:DO 闲置一段时间会被 evict,内存里的数据丢失,务必所有状态都写到 SQLite 而不是放在 this.xxx 字段。
6. 限流配置:Workers 免费版每分钟 1000 次请求,超过会拒绝。生产环境需要设置合理的 limits,在 wrangler.toml 调 limits.cpu_ms。

初级用法

1. 实时计数器:每个 ID 一个 DO 实例,GET 增加,GET 读取,适合做”页面浏览量”、“点赞数”。
2. WebSocket 聊天室:一个房间 ID 一个 DO,所有连接订阅同一个实例,消息广播靠 this.getWebSockets().forEach(ws => ws.send(...))。
3. 分布式限流:用 DO 做 token bucket,API 网关层面调用 DO 决定是否放行,比 Redis 限流延迟更低。

高级玩法

1. 实时协作:用 DO + CRDT(Y.js / Automerge)做多人协同编辑,类似 Figma 多人光标,适合做在线文档。
2. 跨区域数据同步:在 DO 里订阅其他 DO 的 SQLite 变更(支持 change streams),实现”全球数据最终一致”。
3. AI Agent 状态机:用 DO 跑长时任务(几分钟到几小时),把中间状态存 SQLite,前端轮询查询进度。

小技巧

• 给 DO 取 ID 时加上业务前缀(如 chat:room-123),方便按前缀做批量清理和监控。
• Hibernation 模式下,WebSocket 重新唤醒会重新触发 webSocketMessage,记得加幂等。
• 写 DO 时强制”先写日志再改状态”,便于事后追溯。
• 监控 DO 用 wrangler tail 实时看日志,比 Cloudflare Dashboard 的延迟低。
• 本地开发用 wrangler dev --test-scheduled,可以在本地模拟 cron 触发。

常见问题 FAQ

Q1: 这个 Skill 跟 cloudflare-durable-objects 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: cloudflare-durable-objects 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 cloudflare-durable-objects 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 cloudflare-durable-objects,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/cloudflare/skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• Skill 仓库:https://github.com/cloudflare/skills
• Cloudflare Workers 文档:https://developers.cloudflare.com/workers/
• Durable Objects 官方文档:https://developers.cloudflare.com/durable-objects/
• Hibernation API 指南:https://developers.cloudflare.com/durable-objects/api/hibernatable-websockets/
• Wrangler CLI:https://developers.cloudflare.com/workers/wrangler/

我的个人推荐(测试编辑 Mnet)

最常用的 1 个核心用法:每天打开 Agent 第一时间加载这个 Skill,既不消耗太多 token 也能规范输出。

最容易踩的坑:别把 Skill 提示词当”开箱即用”的最终答案——它只是给你一个”标准框架”,具体项目还得你自己调整。

适合人群:做过 3+ 个实际项目的开发者,而不是”看一遍文档就完事”的小白。

3 个月使用心得:刚开始用时觉得”规范是约束”,用了 3 个月后才发现”规范是省时间”——避免每次重新决策同样的细节。

推荐配合的工具:Claude Code / Cursor / OpenCode 任选一个主流 Agent 即可,不要在工具选择上纠结太久。

长期价值:这类 Skill 的核心价值不是”立竿见影的输出”,而是”持续一致的质量”——长期用下来,你的项目质量会稳定在专业水平。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。