📚 云平台 全难度 📦 community

cloudflare-durable-objects

Cloudflare Durable Objects 全套最佳实践、避坑指南。

7 /10 ★★★★☆
#免费#部署运维#自动化
📄 相关文章

📊 评分明细

📦 打包完整度
1.8 1.8 / 2.5
🎯 实用性
1.8 1.8 / 2.5
📖 文档清晰度
1.4 1.4 / 2
👥 社区影响力
1.1 1.1 / 1.5
🔗 集成度
1.1 1.1 / 1.5

🎯 适用场景

免费部署运维自动化

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<br>
```<br>
仓库:https://github.com/cloudflare/skills<br>
### 第 2 步:创建 Worker 项目<br>
```bash<br>
npm create cloudflare@latest my-do-app -- --template worker-durable-object<br>
cd my-do-app<br>
npx wrangler login<br>
```<br>
### 第 3 步:用 Skill 写一个计数器<br>
对 AI 说:<br>
```<br>
用 cloudflare-durable-objects Skill,写一个 Worker + DO,<br>
GET /counter/:id 增加并返回当前计数,数据用 SQLite 存储<br>
```<br>
AI 会输出 `src/index.ts`,包含 `DurableObject` 类、`increment()` 方法、`env.DB` 绑定等关键代码。运行 `npx wrangler dev` 启动,curl `http://localhost:8787/counter/abc` 即可看到数字递增。<br>
## 常见踩坑<br>
1. **WebSocket Hibernation 没用**:开了 DO 但没用 Hibernation API,长连接空闲时仍按请求计费,账单爆炸。`this.ctx.acceptWebSocket(server)` + `webSocketMessage` 事件是正确姿势。<br>
2. **SQLite 写并发阻塞**:DO 的 SQLite 是单写多读,大量并发写会卡住。务必用 `blockConcurrencyWhile` 包装写操作,或者合并写入。<br>
3. **跨区域 ID 路由**:DO 默认按 ID 哈希路由到固定区域,如果你用了 `locationHint` 但 ID 没带地理前缀,会出现"用户 A 写入、用户 B 读不到"的情况。<br>
4. **本地开发与生产不一致**:`wrangler dev` 用的 SQLite 是内存版的,某些边界行为(并发、断电恢复)和生产不一致,关键路径要在 `wrangler dev --remote` 上跑。<br>
5. **Eviction(驱逐)与持久化矛盾**:DO 闲置一段时间会被 evict,内存里的数据丢失,务必所有状态都写到 SQLite 而不是放在 this.xxx 字段。<br>
6. **限流配置**:Workers 免费版每分钟 1000 次请求,超过会拒绝。生产环境需要设置合理的 limits,在 wrangler.toml 调 `limits.cpu_ms`。<br>
## 初级用法<br>
1. **实时计数器**:每个 ID 一个 DO 实例,GET 增加,GET 读取,适合做"页面浏览量"、"点赞数"。<br>
2. **WebSocket 聊天室**:一个房间 ID 一个 DO,所有连接订阅同一个实例,消息广播靠 `this.getWebSockets().forEach(ws => ws.send(...))`。<br>
3. **分布式限流**:用 DO 做 token bucket,API 网关层面调用 DO 决定是否放行,比 Redis 限流延迟更低。<br>
## 高级玩法<br>
1. **实时协作**:用 DO + CRDT(Y.js / Automerge)做多人协同编辑,类似 Figma 多人光标,适合做在线文档。<br>
2. **跨区域数据同步**:在 DO 里订阅其他 DO 的 SQLite 变更(支持 change streams),实现"全球数据最终一致"。<br>
3. **AI Agent 状态机**:用 DO 跑长时任务(几分钟到几小时),把中间状态存 SQLite,前端轮询查询进度。<br>
## 小技巧<br>
- 给 DO 取 ID 时加上业务前缀(如 `chat:room-123`),方便按前缀做批量清理和监控。<br>
- Hibernation 模式下,WebSocket 重新唤醒会重新触发 `webSocketMessage`,记得加幂等。<br>
- 写 DO 时强制"先写日志再改状态",便于事后追溯。<br>
- 监控 DO 用 `wrangler tail` 实时看日志,比 Cloudflare Dashboard 的延迟低。<br>
- 本地开发用 `wrangler dev --test-scheduled`,可以在本地模拟 cron 触发。<br>
## 常见问题 FAQ<br>
**Q1: 这个 Skill 跟 cloudflare-durable-objects 有什么关系?必须装吗?**<br>
A: Skill 是给 AI Agent 用的"技能包",能告诉 Agent 怎么按特定规范工作。**不是必须装**——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。<br>

**Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?**<br>
A: cloudflare-durable-objects 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。<br>

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

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

**Q5: 这个 Skill 有许可证吗?能商用吗?**<br>
A: 取决于 cloudflare-durable-objects 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。<br>
## 参考链接
- [Skill 仓库](https://github.com/cloudflare/skills)<br>
- [Cloudflare Workers 文档](https://developers.cloudflare.com/workers/)<br>
- [Durable Objects 官方文档](https://developers.cloudflare.com/durable-objects/)<br>
- [Hibernation API 指南](https://developers.cloudflare.com/durable-objects/api/hibernatable-websockets/)<br>
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)<br>
---


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

cloudflare-durable-objects Skill 多维度简评

类别：后端开发 来源：cloudflare/skills 定位：Cloudflare Durable Objects 开发 Skill——帮助 AI Agent 构建状态化的边缘计算应用。

说明：本文基于官方文档和公开资料整理，未经过 MagicNetWorld 实测。

一、核心定位与价值

Cloudflare Durable Objects（DO）是 Cloudflare 提供的状态化边缘计算服务，是 Cloudflare Workers 的”有状态”扩展。每个 Durable Object 拥有全局唯一名称、持久化存储以及强一致性保证。它位于传统”集中式单源服务器”和现代”分布式无状态函数”之间的中间地带——既有分布式 API 的全球可达性，又有个体实例的强一致性和状态保持。

cloudflare/skills 是 Cloudflare 官方发布的 Agent Skill 仓库，其中的 durable-objects Skill 为 AI 编码 Agent 提供了 Durable Objects 开发的完整指导，涵盖 RPC 方法实现、SQLite 存储、Alarms API、WebSocket Hibernation、Wrangler 配置和 Vitest 测试。

核心价值：让 AI Agent 掌握 Durable Objects 的开发范式——在边缘实现强一致性的状态管理，适用于实时协作、游戏、聊天室等场景。

二、Durable Objects 核心概念

Durable Objects 与普通 Workers 的关键区别：

特性WorkersDurable Objects
状态无状态（需外部存储）有状态（内建持久化 + 内存）
一致性最终一致性强一致性
实例全球分布式，无法寻址全局唯一名称，可精确寻址
存储KV、R2、D1（外部）SQLite 内嵌存储
伸缩自动水平伸缩单实例串行处理请求

三、核心能力

能力说明
状态化 Worker每个 DO 实例拥有全局唯一标识和持久化状态
WebSocket HibernationWebSocket 连接休眠机制，降低空闲连接成本
SQLite 存储内嵌 SQLite，通过 sql.exec 直接执行 SQL
Alarm API定时触发机制，支持 TTL、定时任务和周期性操作
RPC 方法通过 idFromName / getByName 进行跨 DO 的 RPC 调用
Vitest 测试通过 @cloudflare/vitest-pool-workers 编写单元和集成测试

四、安装与使用

# 通过 npx 安装
npx skills add https://github.com/cloudflare/skills --skill durable-objects

# 或手动克隆
git clone https://github.com/cloudflare/skills

创建 DO 项目

npm create cloudflare@latest -- durable-object-starter
# 选择 "Hello World example" → "Worker + Durable Objects"

Skill 内置参考文档

该 Skill 包含三个内置参考文件：

  • references/rules.md — 核心规则、存储、并发、RPC、Alarms
  • references/testing.md — Vitest 设置、单元/集成测试、Alarm 测试
  • references/workers.md — Workers 处理器、类型、Wrangler 配置

五、使用场景

  • 实时协作工具：多用户同时编辑文档、白板、表格
  • 聊天室/消息系统：通过 WebSocket + DO 实现房间状态管理
  • 多人游戏：游戏房间的状态同步和逻辑执行
  • 预订系统：座位/资源预订的并发控制和状态管理
  • 分布式计数器/限流器：全局唯一的计数和速率限制

六、Cloudflare DO 最佳实践

根据官方文档，Durable Objects 开发中应遵循：

  • 使用 blockConcurrencyWhile 确保关键操作的串行执行
  • 合理使用 idFromName 和 getByName 管理 DO 实例
  • 利用 setAlarm 实现定时清理、TTL 和周期性任务
  • SQLite 存储已从 Beta 进入 GA，新 DO 类应使用 SQLite 存储
  • Free 计划也支持 SQLite 存储（有配额限制）

七、注意事项

  • DO 实例按请求计费，空闲实例也会产生存储费用
  • 每个 DO 实例串行处理请求，需要注意避免单个实例成为瓶颈
  • WebSocket Hibernation 是降低 WebSocket 成本的关键机制
  • 该 Skill 提供的是开发指导，具体代码实现需要结合 Cloudflare Workers 运行时

参考资料

📊 评分与标签

评分说明

总分 7.0/10 · S_入选

📊 可观测社区指标（数据核验日期：2026-07-23）

📦 可安装性 1.7/2.5

  • 可从官方仓库加载独立目录，但真正运行仍依赖 Wrangler、Cloudflare 项目配置及对应产品权限。
  • 对比 Firebase Agent Skills、Supabase MCP：本项安装边界与依赖透明度按官方资料计分，未把平台账号或宿主能力误算为 Skill 自身能力。

🎯 实用性 2.0/2.5

  • 专门 Skill 与 references 涵盖 Durable Objects、测试和 Workers 集成，可辅助状态协调与 WebSocket 场景。
  • 对比 Firebase Agent Skills、Supabase MCP：评分关注本项能解决的具体任务与约束，不以仓库热度代替实际功能证据。

📖 文档质量 1.4/2.0

  • 提供 rules、testing、workers 三类参考，主题集中；对复杂迁移和生产容量规划仍需回到 Cloudflare 产品文档。
  • 对比 Firebase Agent Skills、Supabase MCP：能从公开资料复核的安装、边界和示例计入本维度，无法复核的宣传性描述未计分。

👥 社区活跃 0.8/1.5

  • 与 Cloudflare Skills 总仓共享 ★2,453、Fork 229；该数字不能视作 Durable Objects 单项采用量。
  • 社区分只反映核验日可观察的仓库级信号；与 Firebase Agent Skills、Supabase MCP 的规模差异不直接推导输出质量。

🔗 兼容性 1.1/1.5

  • 适合 Markdown Skill Agent 与 Workers 开发链，超出 Cloudflare 运行时的后端平台不能原样复用。
  • 对比 Firebase Agent Skills、Supabase MCP：兼容性按已公开支持的协议、平台和运行条件计分，不推定未声明的客户端可用。

评分依据可追溯至公开来源，每项分数均有明确理由和数据支撑。

局限与使用边界

  • 评分较低反映单项安装边界、独立社区指标缺失及平台锁定；不能仅凭 Skill 替代负载测试和架构评审。
  • 本评分是公开资料审查，不代表在所有宿主、账号权限和生产数据集上完成独立实测。

🏷️ 标签说明

  • 免费: 该标签对应条目公开描述与仓库能力边界。来源：主要核验来源
  • 部署运维: 该标签对应条目公开描述与仓库能力边界。来源：主要核验来源
  • 自动化: 该标签对应条目公开描述与仓库能力边界。来源：主要核验来源

📋 来源核验记录

  • ✅ 已核验：主要官方来源
  • ✅ 已核验：GitHub 仓库或登记地址
  • ✅ 已核验：GitHub API 元数据
  • ⚠️ 间接来源：站内 JSON 的名称、标签与固定总分仅用于一致性校验，维度证据以以上公开来源为准。
  • ❌ 已删除死链：无；若登记仓库返回 404，已在正文明确标注并未引用其社区数字。