# Cloudflare 耐用对象 **状态**：生产就绪 ✅ **最后更新**：2025-11-23 **依赖项**：cloudflare-worker-base（推荐）**最新版本**：wrangler@4.50.0、@cloudflare/workers-types@4.20251121.0 **官方文档**： **最近更新（2025）**： * **2025 年 10 月**：WebSocket 消息大小 1 MiB → 32 MiB，SQLite DO 的 Data Studio UI（在仪表板中查看/编辑存储） * **2025 年 8 月**：命名 DO 的 `getByName()` API 快捷方式 * **2025 年 6 月**：@cloudflare/actors 库（测试版）- 推荐包含迁移、警报、Actor 类模式的 SDK * **2025 年 5 月**：Python Workers 支持持久对象 * **2025 年 4 月**：SQLite GA，具有 10GB 存储空间（测试版 → GA，1GB → 10GB），免费套餐访问 * **2025 年 2 月**：PRAGMA 优化支持，通过参考 ID 改进错误诊断 ** ** ## 快速入门 **搭建新的 DO 项目：** npm create cloudflare@latest my-durable-app -- --template=cloudflare/durable-objects-template --ts **或者添加到现有的Worker中：** // src/counter.ts - 持久对象类从 'cloudflare:workers' 导入 { DurableObject }; 导出类 Counter 扩展 DurableObject { 异步增量(): Promise { 让 value = (await this.ctx.storage.get('value')) || 0; 等待 this.ctx.storage.put('value', ++value); 返回值； } } 导出默认计数器； // 关键：需要导出 // wrangler.jsonc - 配置 { “耐用对象”：{ “绑定”：[{“名称”：“计数器”，“类名”：“计数器”}] }, “迁移”：[ { "tag": "v1", "new_sqlite_classes": ["Counter"] } // SQLite 后端（10GB 限制） ] } // src/index.ts - 工人从 './counter' 导入 { Counter } ；导出{计数器}；导出默认值{ 异步获取（请求：请求，环境：{ COUNTER：DurableObjectNamespace }）{ const 存根 = env.COUNTER.getByName('全局计数器'); // 2025 年 8 月：getByName() 快捷方式返回新的响应（`计数：$ {等待存根.increment（）}`）; } }; ** ** ## DO 课程要点从 'cloudflare:workers' 导入 { DurableObject }; 导出类 MyDO 扩展 DurableObject { 构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； // 必需的第一行 // 请求之前加载状态（可选） ctx.blockConcurrencyWhile(async () => { this.value = wait ctx.storage.get('key') ||默认值； }); } // RPC 方法（推荐） async myMethod(): Promise { return 'Hello'; } // HTTP 获取处理程序（可选）异步获取（请求：请求）： Promise { return new Response('OK'); } } 导出默认MyDO； // 关键：需要导出 // Worker 也必须导出 DO 类从 './my-do' 导入 { MyDO }；导出{MyDO}； **构造函数规则：** * ✅ 首先调用 `super(ctx, env)` * ✅ 保持最低限度 - 繁重的工作会阻碍冬眠唤醒 * ✅ 使用 `ctx.blockConcurrencyWhile()` 进行存储初始化 * ❌ 切勿`setTimeout`/`setInterval`（使用闹钟） * ❌ 不要依赖 WebSocket 的内存状态（持久存储） ** ** ## 存储API **两个可用后端：** * **SQLite**（推荐）：10GB 存储、SQL 查询、原子操作、PITR * **KV** ：128MB 存储，仅键值 **在迁移中启用 SQLite：** {“迁移”：[{“标签”：“v1”，“new_sqlite_classes”：[“MyDO”]}]} ### SQL API（SQLite 后端）导出类 MyDO 扩展 DurableObject { sql：SqlStorage；构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sql = ctx.storage.sql; 这个.sql.exec(` 如果不存在则创建表消息（id INTEGER PRIMARY KEY、文本 TEXT、created_at INTEGER）；如果不存在则创建索引 idx_created ON messages(created_at); PRAGMA优化； // 2025 年 2 月：查询性能优化 `); } async addMessage(text: string): Promise { const 游标 = this.sql.exec('INSERT INTO messages (text,created_at) VALUES (?, ?) RETURNING id', text, Date.now()); 返回cursor.one<{ id: number }>().id; } 异步 getMessages(limit = 50): Promise { return this.sql.exec('SELECT * FROM messages ORDER BYcreated_at DESC LIMIT ?', limit).toArray(); } } **SQL 方法：** * `sql.exec(query, ...params)` → 游标 * `cursor.one()` → 单行（如果没有则抛出） * `cursor.one({ allowedNone: true })` → row 或 null * `cursor.toArray()` → 所有行 * `ctx.storage.transactionSync(() => { ... })` → 原子多语句 **规则：** 始终使用“?”占位符、创建索引、在架构更改后使用 PRAGMA 优化 ### 键值 API（两个后端） // 单个操作等待 this.ctx.storage.put('key', value); const value = wait this.ctx.storage.get('key'); 等待 this.ctx.storage.delete('key'); // 批量操作等待 this.ctx.storage.put({ key1: val1, key2: val2 }); const map = wait this.ctx.storage.get(['key1', 'key2']); 等待 this.ctx.storage.delete(['key1', 'key2']); // 列出并删除所有 const map = wait this.ctx.storage.list({ 前缀: '用户:', 限制: 100 }); 等待 this.ctx.storage.deleteAll(); // 仅限 SQLite 上的原子性 // 交易等待 this.ctx.storage.transaction(async (txn) => { 等待 txn.put('key1', val1); 等待 txn.put('key2', val2); }); **存储限制：** SQLite 10GB（2025 年 4 月正式版）| 128MB ** ** ## WebSocket 休眠 API **能力：** * 每个实例数千个 WebSocket 连接 * 闲置时休眠（约 10 秒无活动）以节省成本 * 消息到达时自动唤醒 * **消息大小限制**：32 MiB（2025 年 10 月，高于 1 MiB） **它是如何工作的：** 1. 主动→处理消息 2. 空闲 → ~10 秒无活动 3.休眠→内存状态**清除**，WebSockets保持连接 4.唤醒→消息到达→构造函数运行→处理程序调用 **关键：**内存中状态**在休眠时丢失**。使用“serializeAttachment()”来保存每个 WebSocket 元数据。 ### 休眠安全模式导出类 ChatRoom 扩展 DurableObject { 会话：Map; 构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sessions = new Map(); // 关键：休眠后恢复 WebSocket 元数据 ctx.getWebSockets().forEach((ws) => { this.sessions.set(ws, ws.deserializeAttachment()); }); } 异步获取（请求：请求）：Promise { constpair = new WebSocketPair(); const [客户端，服务器] = Object.values(pair); const url = 新 URL(request.url); const 元数据 = { userId: url.searchParams.get('userId'), 用户名: url.searchParams.get('用户名') }; // 关键：使用 ctx.acceptWebSocket()，而不是 ws.accept() this.ctx.acceptWebSocket(服务器); server.serializeAttachment（元数据）； // 休眠期间持续存在 this.sessions.set（服务器，元数据）；返回新的 Response(null, { 状态: 101, webSocket: 客户端 }); } async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise { const 会话 = this.sessions.get(ws); // 处理消息（自 2025 年 10 月起最大 32 MiB） } async webSocketClose(ws: WebSocket, 代码: 数字, 原因: 字符串, wasClean: 布尔值): Promise { this.sessions.delete(ws); ws.close(code, '关闭'); } 异步 webSocketError(ws: WebSocket, 错误: 任何): Promise { this.sessions.delete(ws); } } **休眠规则：** * ✅ `ctx.acceptWebSocket(ws)` \- 启用休眠 * ✅ `ws.serializeAttachment(data)` \- 持久化元数据 * ✅ `ctx.getWebSockets().forEach()` \- 在构造函数中恢复 * ✅ 使用闹钟代替 `setTimeout`/`setInterval` * ❌ `ws.accept()` \- 标准 API，无休眠 * ❌ `setTimeout`/`setInterval` \- 防止休眠 * ❌ 进行中 `fetch()` \- 阻止休眠 ** ** ## 警报 API 安排 DO 在未来的时间醒来。 **用于：**批处理、清理、提醒、定期任务。导出类 Batcher 扩展 DurableObject { 异步 addItem(item: string): Promise { // 添加到缓冲区 const buffer = wait this.ctx.storage.get('buffer') || []；缓冲区.push(项目); 等待 this.ctx.storage.put('buffer', buffer); // 如果没有设置则安排闹钟 if ((await this.ctx.storage.getAlarm()) === null) { 等待 this.ctx.storage.setAlarm(Date.now() + 10000); // 10 秒 } } 异步警报（信息：{ retryCount：number; isRetry：boolean }）：Promise { if (info.retryCount > 3) 返回； // 重试3次后放弃 const buffer = wait this.ctx.storage.get('buffer') || []；等待 this.processBatch(buffer); 等待 this.ctx.storage.put('buffer', []); // 报警成功后自动删除 } } **API方法：** * `await ctx.storage.setAlarm(Date.now() + 60000)` \- 设置闹钟（覆盖现有） * `await ctx.storage.getAlarm()` \- 获取时间戳或 null * `await ctx.storage.deleteAlarm()` \- 取消闹钟 * `async Alarm(info)` \- 警报触发时调用处理程序 **行为：** * ✅ 至少执行一次，自动重试（最多 6 次，指数退避） * ✅ 在冬眠/驱逐中幸存下来 * ✅ 成功后自动删除 * ⚠️ 每个 DO 一个警报（新警报覆盖） ** ** ## RPC 与 HTTP 获取 **RPC（推荐）：** 直接方法调用，类型安全，简单 // DO 类导出类 Counter 扩展 DurableObject { 异步增量(): Promise { 让 value = (await this.ctx.storage.get('count')) || 0; 等待 this.ctx.storage.put('count', ++value); 返回值； } } // 工人调用 const 存根 = env.COUNTER.getByName('my-counter'); const count =等待存根.increment(); // 类型安全！ **HTTP Fetch：** 请求/响应模式，WebSocket 升级所需 // DO 类导出类 Counter 扩展 DurableObject { 异步获取（请求：请求）：Promise { const url = 新 URL(request.url); if (url.pathname === '/increment') { 让 value = (await this.ctx.storage.get('count')) || 0; 等待 this.ctx.storage.put('count', ++value); 返回新的 Response(JSON.stringify({ count: value })); } return new Response('未找到', { status: 404 }); } } // 工人调用 const 存根 = env.COUNTER.getByName('my-counter'); const response = wait Stub.fetch('https://fake-host/increment', { method: 'POST' }); const data =等待response.json(); **何时使用：** 用于新项目的 RPC（更简单）、用于 WebSocket 升级或复杂路由的 HTTP Fetch ** ** ## 获取 DO 存根 **获取ID的三种方法：** 1. **`idFromName(name)`** \- 一致的路由（相同的名称=相同的DO） const 存根 = env.CHAT_ROOM.getByName('room-123'); // 2025 年 8 月：idFromName + get 的快捷方式 // 用于：聊天室、用户会话、每租户逻辑、单例 2. **`newUniqueId()`** \- 随机唯一 ID（必须存储以供重用） const id = env.MY_DO.newUniqueId({ 管辖范围: 'eu' }); // 可选：欧盟合规性 const idString = id.toString(); // 保存到 KV/D1 供以后使用 3. **`idFromString(idString)`** \- 从保存的 ID 重新创建 const id = env.MY_DO.idFromString(await env.KV.get('会话：123')); const 存根 = env.MY_DO.get(id); **位置提示（尽力）：** const 存根 = env.MY_DO.get(id, { locationHint: 'enam' }); // wnam、enam、sam、weur、eeur、apac、oc、afr、me **管辖范围（严格执行）：** const id = env.MY_DO.newUniqueId({ 管辖范围: 'eu' }); // 选项: 'eu', 'fedramp' // 无法与位置提示结合，管辖范围之外的延迟较高 ** ** ## 迁移 **需要：** 创建、重命名、删除、传输 DO 类 **1\.创建：** { "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }] } // SQLite 10GB // 或者： "new_classes": ["Counter"] // KV 128MB（旧版） **2\.重命名：** {“迁移”：[ { "tag": "v1", "new_sqlite_classes": ["OldName"] }, { "tag": "v2", "renamed_classes": [{ "from": "OldName", "to": "NewName" }] } ]} **3\.删除：** {“迁移”：[ {“标签”：“v1”，“new_sqlite_classes”：[“计数器”]}， { "tag": "v2", "deleted_classes": ["Counter"] } // 立即删除，无法撤消 ]} **4\.转账：** {“迁移”：[{“标签”：“v1”，“transferred_classes”：[ { "from": "OldClass", "from_script": "old-worker", "to": "NewClass" } ]}]} **迁移规则：** * ❌ 原子（所有实例立即迁移，无需逐步推出） * ❌ 标签是唯一的并且只能附加 * ❌ 无法在现有 KV 支持的 DO 上启用 SQLite * ✅ 代码更改不需要迁移（仅架构更改） * ✅ 每个帐户的类名称全局唯一 ** ** ## 常见模式 **速率限制：** async checkLimit(userId: string, limit: number, window: number): Promise { const requests = (await this.ctx.storage.get(`rate:${userId}`)) || []； const valid = requests.filter(t => Date.now() - t < window); if (valid.length >= limit) 返回 false; valid.push(Date.now()); 等待 this.ctx.storage.put(`rate:${userId}`, valid); 返回真； } **使用 TTL 进行会话管理：** 异步集（键：字符串，值：任意，ttl？：数字）：Promise { const 过期时间 = ttl ? Date.now() + ttl : null; this.sql.exec('插入或替换会话(key, value, expires_at) VALUES (?, ?, ?)', key, JSON.stringify(value), expiresAt); } 异步闹钟(): Promise { this.sql.exec('从会话中删除expires_at < ?', Date.now()); 等待 this.ctx.storage.setAlarm(Date.now() + 3600000); // 每小时清理一次 } **领导人选举：** async electLeader(workerId: string): Promise { 尝试{ this.sql.exec('插入领导者(id,worker_id,elected_at)VALUES(1,?,?)',workerId,Date.now()); 返回真； } catch { 返回 false; } // 已经有领导者了 } **多 DO 协调：** // 协调者委托给子 DO const gameRoom = env.GAME_ROOM.getByName(gameId); 等待 gameRoom.initialize(); 等待 this.ctx.storage.put(`游戏:${gameId}`, { 创建: Date.now() }); ** ** ## 关键规则 ### 总是这样做 ✅ **从 Worker 导出 DO 类** 导出类 MyDO 扩展 DurableObject { } 导出默认MyDO； // 必填 ✅ **在构造函数中调用`super(ctx, env)`** 构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； // 需要第一行 } ✅ **对新 DO 使用`new_sqlite_classes`** {“标签”：“v1”，“new_sqlite_classes”：[“MyDO”]} ✅ **使用`ctx.acceptWebSocket()`**进行休眠 this.ctx.acceptWebSocket(服务器); // 启用休眠 ✅ **将关键状态**保留到存储（不仅仅是内存）等待 this.ctx.storage.put('重要', 值); ✅ **使用闹钟**而不是 setTimeout/setInterval 等待 this.ctx.storage.setAlarm(Date.now() + 60000); ✅ **使用参数化 SQL 查询** this.sql.exec('SELECT * FROM table WHERE id = ?', id); ✅ **最大限度地减少施工人员工作** 构造函数（ctx，env）{ 超级（ctx，环境）； // 仅进行最小初始化 ctx.blockConcurrencyWhile(async () => { // 从存储加载 }); } ### 永远不要这样做 ❌ **创建 DO 而不迁移** // 缺少迁移数组 = 错误 ❌ **忘记导出 DO 类** 类 MyDO 扩展 DurableObject { } // 缺少：导出默认MyDO； ❌ **使用`setTimeout`或`setInterval`** setTimeout(() => {}, 1000); // 防止休眠 ❌ **仅依靠 WebSocket 的内存状态** // ❌ 错误：this.sessions 将在休眠时丢失 // ✅ 正确：使用serializeAttachment() ❌ **逐步部署迁移** # 迁移是原子的 - 不能使用逐步推出 ❌ **在现有 KV 支持的 DO 上启用 SQLite** // 不支持 - 必须创建新的 DO 类 ❌ **使用标准 WebSocket API** 期待休眠 ws.accept(); // ❌ 不休眠 this.ctx.acceptWebSocket(ws); // ✅ 启用休眠 ❌ **假设位置提示得到保证** // 位置提示仅尽力而为 ** ** ## 已知问题预防此技能可防止 **15+ 已记录的问题**： ### 问题#1：类未导出 **错误**：“找不到绑定”或“找不到 X 类”**来源**： **为什么会发生**：DO 类未从 Worker 导出 **预防**：导出类 MyDO 扩展 DurableObject { } 导出默认MyDO； // ← 必需 ### 问题 #2：缺少迁移 **错误**：“需要迁移”或“未找到类迁移”**来源**： **为什么发生**：创建没有迁移条目的 DO 类 **预防**：创建新 DO 类时始终添加迁移 { “迁移”：[ {“标签”：“v1”，“new_sqlite_classes”：[“MyDO”]} ] } ### 问题 #3：错误的迁移类型（KV 与 SQLite） **错误**：架构错误，存储 API 不匹配 **来源**： **为什么会发生**：使用 `new_classes` 而不是 `new_sqlite_classes` **预防**：将 `new_sqlite_classes` 用于 SQLite 后端（推荐） ### 问题 #4：构造函数开销阻止休眠唤醒 **错误**：休眠唤醒时间慢 **来源**： **为什么发生**：构造函数中的繁重工作 **预防**：最小化构造函数，使用 `blockConcurrencyWhile()` 构造函数（ctx，env）{ 超级（ctx，环境）； ctx.blockConcurrencyWhile(async () => { // 从存储加载 }); } ### 问题 #5：setTimeout 打破休眠状态 **错误**：从不休眠，持续时间费用高 **来源**： **为什么会发生**：`setTimeout`/`setInterval` 防止休眠 **预防**：改用警报 API // ❌ 错误 setTimeout(() => {}, 1000); // ✅ 正确等待 this.ctx.storage.setAlarm(Date.now() + 1000); ### 问题 #6：休眠时内存状态丢失 **错误**：WebSocket 元数据丢失，状态意外重置 **来源**： **为什么会发生**：依赖于休眠时清除的内存状态 **预防**：对 WebSocket 元数据使用 `serializeAttachment()` ws.serializeAttachment({ userId, 用户名 }); // 在构造函数中恢复 ctx.getWebSockets().forEach(ws => { const 元数据 = ws.deserializeAttachment(); this.sessions.set(ws, 元数据); }); ### 问题 #7：传出 WebSocket 无法休眠 **错误**：尽管有休眠 API，费用仍然很高 **来源**： **为什么会发生**：传出 WebSocket 不支持休眠 **预防**：仅对服务器端（传入）WebSocket 使用休眠 ### 问题 #8：全球独特性混乱 **错误**：意外的 DO 类名称冲突 **来源**： **为什么会发生**：DO 类名称在每个帐户中都是全局唯一的 **预防**：了解 DO 类名称在帐户中的所有工作人员之间共享 ### 问题#9：KV 后端部分删除全部 **错误**：存储未完全删除，计费继续 **来源**： **为什么发生**：KV 后端 `deleteAll()` 可能部分失败 **预防**：使用 SQLite 后端进行原子删除 ### 问题 #10：绑定名称不匹配 **错误**：访问 DO 绑定时出现运行时错误 **来源**： **为什么会发生**：wrangler.jsonc 中的绑定名称与代码不匹配 **预防**：确保一致性 {“绑定”：[{“名称”：“MY_DO”，“class_name”：“MyDO”}]} env.MY_DO.getByName('实例'); // 必须匹配绑定名称 ### 问题#11：状态大小超出 **错误**：“超出状态限制”或存储错误 **来源**： **为什么发生**：超出 1GB (SQLite) 或 128MB (KV) 限制 **预防**：监控存储大小，通过警报实施清理 ### 问题 #12：迁移不是原子的 **错误**：逐步部署被阻止 **来源**： **为什么会发生**：尝试使用逐步部署和迁移 **预防**：迁移在所有实例中自动部署 ### 问题#13：位置提示被忽略 **错误**：DO 在错误的区域创建 **来源**： **为什么会发生**：位置提示是尽力而为，不能保证 **预防**：使用管辖权来满足严格要求 ### 问题 #14：警报重试失败 **错误**：警报失败后任务丢失 **来源**： **为什么发生**：警报处理程序重复抛出错误 **预防**：实现幂等警报处理程序异步警报（信息：{ retryCount：number }）：Promise { if (info.retryCount > 3) { console.error('重试3次后放弃'); 返回; } // 幂等操作 } ### 问题 #15：获取块休眠 **错误**：尽管使用休眠 API，但永远不会休眠 **来源**： **为什么发生**：正在进行的 `fetch()` 请求阻止休眠 **预防**：确保所有异步 I/O 在空闲期之前完成 ** ** ## 配置和类型 **牧马人.jsonc：** { “兼容性日期”：“2025-11-23”， “耐用对象”：{ “绑定”：[{“名称”：“计数器”，“类名”：“计数器”}] }, “迁移”：[ {“标签”：“v1”，“new_sqlite_classes”：[“计数器”]}， { "tag": "v2", "renamed_classes": [{ "from": "Counter", "to": "CounterV2" }] } ] } **打字稿：** 从 'cloudflare:workers' 导入 { DurableObject, DurableObjectState, DurableObjectNamespace }; 接口环境 { MY_DO: DurableObjectNamespace; } 导出类 MyDurableObject 扩展 DurableObject { 构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sql = ctx.storage.sql; } } ** ** ## 官方文档 * **持久对象**： * **状态 API (SQL)** ： * **WebSocket 休眠** ： * **警报 API** ： * **迁移** ： * **最佳实践**： * **定价** ： ** ** **有问题吗？有问题吗？** 1. 检查 `references/top-errors.md` 常见问题 2. 查看“templates/”以获取工作示例 3.查阅官方文档： 4. 仔细验证迁移配置

Cloudflare 耐用对象

包含技能