# Cloudflare 耐用对象 **状态**：生产就绪 ✅ **最后更新**：2025-10-22 **依赖项**：cloudflare-worker-base（推荐）**最新版本**：wrangler@4.43.0+、@cloudflare/workers-types@4.20251014.0+ **官方文档**： ** ** ## 什么是耐用对象？ Cloudflare Durable 对象是**全球唯一的有状态对象**，它提供： * **单点协调** \- 每个持久对象实例在 Cloudflare 网络中都是全局唯一的 * **强一致性** \- 事务性、可序列化存储（ACID 保证） * **实时通信** \- 每个实例有数千个连接的 WebSocket 休眠 API * **持久状态** \- 内置SQLite数据库（最大1GB）或键值存储 * **计划任务** \- 用于未来任务执行的警报 API * **全球分布** \- 自动路由到最佳位置 * **自动缩放** \- 数百万个独立实例 **用例**： * 聊天室和实时协作 * 多人游戏服务器 * 速率限制和会话管理 * 领导者选举和协调 * 具有休眠功能的 WebSocket 服务器 * 有状态的工作流程和队列 * 每用户或每房间逻辑 ** ** ## 快速入门（10 分钟） ### 选项 1：支架新 DO 项目 npm create cloudflare@latest my-durable-app -- \ --template=cloudflare/durable-objects-template \ --ts\ --git \ --部署错误 cd 我的耐用应用程序 npm 安装 npm 运行开发 **这会产生什么：** * 完整的耐用对象项目结构 * TypeScript配置 * wrangler.jsonc 带有绑定和迁移 * DO类实现示例 * 工人致电 DO ### 选项 2：添加到现有 Worker cd 我的现有工人 npm install -D @cloudflare/workers-types **创建一个持久对象类** (`src/counter.ts`)：从 'cloudflare:workers' 导入 { DurableObject }; 导出类 Counter 扩展 DurableObject { 异步增量(): Promise { // 从存储中获取当前值（默认为0）让 value: number = (await this.ctx.storage.get('value')) || 0; // 增量值+=1； // 保存回存储等待 this.ctx.storage.put('value', value); 返回值； } 异步 get(): Promise { 返回（等待 this.ctx.storage.get('value')） || 0; } } // 关键：导出类导出默认计数器； **配置wrangler.jsonc：** { "$schema": "node_modules/wrangler/config-schema.json", “姓名”：“我的工人”， "main": "src/index.ts", “兼容性日期”：“2025-10-22”， // 持久对象绑定 “耐用对象”：{ “绑定”：[ { "name": "COUNTER", // 如何访问它：env.COUNTER "class_name": "Counter" // 必须匹配导出的类名 } ] }, // 必需：迁移新的 DO 类 “迁移”：[ { "tag": "v1", // 唯一迁移标识符 "new_sqlite_classes": [ // 使用 SQLite 后端（推荐） “柜台” ] } ] } **来自 Worker 的调用** (`src/index.ts`)：从 './counter' 导入 { Counter } ；接口环境{ 计数器：DurableObjectNamespace<计数器>； } 导出{计数器}；导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { // 通过名称获取持久对象存根 const id = env.COUNTER.idFromName('全局计数器'); const 存根 = env.COUNTER.get(id); // 在DO上调用RPC方法 const count =等待存根.increment(); 返回新的响应（`计数：$ {count}`）； }, }; **部署：** npx 牧马人部署 ** ** ## 持久对象类结构 ### 基类模式所有持久对象 **必须从 `cloudflare:workers` 扩展 `DurableObject`**：从 'cloudflare:workers' 导入 { DurableObject }; 导出类 MyDurableObject 扩展 DurableObject { 构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； // 可选：从存储初始化 ctx.blockConcurrencyWhile(async () => { // 在处理请求之前加载状态 this.someValue = wait ctx.storage.get('someKey') ||默认值； }); } // RPC 方法（推荐）异步 myMethod(): Promise { 返回“来自 DO 的问候！”； } // 可选：HTTP 获取处理程序异步获取（请求：请求）：Promise { return new Response('Hello from DO fetch!'); } } // 关键：导出类导出默认 MyDurableObject； ### 构造函数模式构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； // 必需 // 访问环境绑定 this.env = env; // this.ctx 提供： // - this.ctx.storage（存储 API） // - this.ctx.id（唯一ID） // - this.ctx.waitUntil()（后台任务） // - this.ctx.acceptWebSocket()（WebSocket 休眠） } **关键规则：** * ✅ **始终先调用`super(ctx, env)`** * ✅ **保持构造函数最小化** \-繁重的工作会阻止休眠唤醒 * ✅ **使用`ctx.blockConcurrencyWhile()`**在请求之前从存储中初始化 * ❌ **永远不要使用 `setTimeout` 或 `setInterval`** \- 打破休眠状态（使用闹钟代替） * ❌ **不要仅依赖 WebSocket 的内存状态** - 持久保存到存储 ### 导出类 // 默认导出（Worker 使用时需要）导出默认 MyDurableObject； // 也导出为命名导出（用于 Worker 中的类型推断）导出 { MyDurableObject }; **在工人中：** // 导入类型的类从 './my-durable-object' 导入 { MyDurableObject } ； // 导出它以便 Worker 可以实例化它导出 { MyDurableObject }; 接口环境{ MY_DO: DurableObjectNamespace; } ** ** ## 状态 API - 持久存储 Durable Objects 根据后端提供**两个存储 API**： 1. **SQL API**（SQLite 后端）- **推荐** 2. **Key-Value API**（KV或SQLite后端） ### 启用 SQLite 后端（推荐）在 `wrangler.jsonc` 迁移中： { “迁移”：[ { “标签”：“v1”， "new_sqlite_classes": ["MyDurableObject"] // ← 将其用于 SQLite } ] } **为什么选择 SQLite？** * ✅ 高达 **1GB 存储空间**（KV 后端为 128MB） * ✅ **原子操作**（deleteAll 是全有或全无） * ✅ **带有事务的 SQL 查询** * ✅ **时间点恢复** (PITR) * ✅ 同步 KV API 也可用 ### SQL API 通过`ctx.storage.sql`访问：从 'cloudflare:workers' 导入 { DurableObject }; 导出类 MyDurableObject 扩展 DurableObject { sql：SqlStorage；构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sql = ctx.storage.sql; // 第一次运行时创建表这个.sql.exec(` 如果不存在则创建表消息（ id 整数主键自动增量，文本文本不为空，用户文本不为空， create_at INTEGER NOT NULL ）；如果不存在则创建索引 idx_created_at ON messages(created_at); `); } async addMessage(text: string, user: string): Promise { // 使用 exec 插入（返回光标） const 游标 = this.sql.exec( '插入消息（文本，用户，created_at）值（？，？，？）返回id'，文字，用户，日期.now() ）； const row = 游标.one<{ id: number }>(); 返回行.id； } async getMessages(limit: number = 50): Promise { const 游标 = this.sql.exec( 'SELECT * FROM messages ORDER BYcreated_at DESC LIMIT ?', 限制）； // 将游标转换为数组返回游标.toArray(); } 异步deleteOldMessages(beforeTimestamp: number): Promise { 这个.sql.exec( '从消息中删除create_at < ?', 之前的时间戳）； } } **SQL API 方法：** // 执行查询（返回光标） const 游标 = this.sql.exec('SELECT * FROM table WHERE id = ?', id); // 获取单行 const row = 游标.one(); // 获取第一行或者为 null const row = 游标.one({ allowedNone: true }); // 获取所有行作为数组 const rows = 游标.toArray(); // 迭代光标 for (光标的常量行) { // 处理行 } // 事务（同步） this.ctx.storage.transactionSync(() => { this.sql.exec('插入表1 ...'); this.sql.exec('更新表2 ...'); // 全有或全无 }); **关键 SQL 规则：** * ✅ 始终使用带有“?”占位符的**参数化查询** * ✅ 为经常查询的列创建索引 * ✅ 使用事务进行多语句操作 * ❌ 不要访问隐藏的`__cf_kv`表（KV API内部使用） * ❌ 不要在现有部署的 KV 支持的 DO 上启用 SQLite（不支持） ### 键值 API 通过 `ctx.storage` 在 **SQLite 和 KV 后端** 上可用：从 'cloudflare:workers' 导入 { DurableObject }; 导出类 MyDurableObject 扩展 DurableObject { 异步增量(): Promise { // 获取值让 count = wait this.ctx.storage.get('count') || 0; // 增量计数 += 1； // 将值放回等待 this.ctx.storage.put('count', count); 返回计数； } 异步batchOperations(): Promise { // 获取多个key const map = wait this.ctx.storage.get(['key1', 'key2', 'key3']); // 放置多个键等待 this.ctx.storage.put({ 键1: '值1', 键2: '值2', 键3: '值3', }); // 删除键等待 this.ctx.storage.delete('key1'); // 删除多个key 等待 this.ctx.storage.delete(['key2', 'key3']); } 异步 listKeys(): Promise { // 列出所有键 const map =等待this.ctx.storage.list(); 返回 Array.from(map.keys()); // 带前缀的列表 const mapWithPrefix = 等待 this.ctx.storage.list({ 前缀：'用户：'，限制：100， }); } 异步deleteAllStorage(): Promise { // 首先删除闹钟（如果设置）等待 this.ctx.storage.deleteAlarm(); // 删除所有存储（DO在关闭后将不复存在）等待 this.ctx.storage.deleteAll(); } } **KV API 方法：** // 获取单个值 const value = wait this.ctx.storage.get('key'); // 获取多个值（返回Map） const map = wait this.ctx.storage.get(['key1', 'key2']); // 输入单个值等待 this.ctx.storage.put('key', value); // 输入多个值等待 this.ctx.storage.put({ key1: value1, key2: value2 }); // 删除单个键等待 this.ctx.storage.delete('key'); // 删除多个key 等待 this.ctx.storage.delete(['key1', 'key2']); // 列出键 const map = 等待 this.ctx.storage.list({ 前缀：'用户：'，限制：100，反向：假 }); // 删除全部（在 SQLite 上是原子的，在 KV 后端上可能是部分的）等待 this.ctx.storage.deleteAll(); // 事务（异步）等待 this.ctx.storage.transaction(async (txn) => { 等待 txn.put('key1', value1); 等待 txn.put('key2', value2); // 全有或全无 }); **存储限制：** * **SQLite 后端**：每个 DO 实例高达 **1GB** 存储空间 * **KV 后端**：每个 DO 实例高达 **128MB** 存储 ** ** ## WebSocket 休眠 API **WebSocket 休眠 API** 允许持久对象： * 每个实例处理 **数千个 WebSocket 连接** * **空闲时休眠**（无消息，无事件）以节省成本 * **消息到达时自动唤醒** * 在空闲期间保持连接，不会产生持续时间费用 **用于：** 聊天室、实时协作、多人游戏、实时更新 ### 休眠如何工作 1. **Active状态** \- DO在内存中，处理消息 2. **空闲状态** \- 约 10 秒内没有消息，DO 可以休眠 3. **休眠** \- 内存状态已清除，WebSocket 保持与 Cloudflare 边缘的连接 4. **唤醒** \- 新消息到达 → 构造函数运行 → 处理程序方法被调用 **关键：**内存中状态**在休眠时丢失**。使用“serializeAttachment()”来保存每个 WebSocket 元数据。 ### WebSocket 服务器模式从 'cloudflare:workers' 导入 { DurableObject }; 导出类 ChatRoom 扩展 DurableObject { 会话：Map; 构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； // 休眠后恢复WebSocket连接 this.sessions = new Map(); ctx.getWebSockets().forEach((ws) => { // 反序列化附件（持久元数据） const 附件 = ws.deserializeAttachment(); this.sessions.set(ws, 附件); }); } 异步获取（请求：请求）：Promise { // 等待WebSocket升级请求 const UpgradeHeader = request.headers.get('升级'); if (upgradeHeader !== 'websocket') { return new Response('预期的 websocket', { status: 426 }); } // 创建 WebSocket 对 const webSocketPair = new WebSocketPair(); const [客户端，服务器] = Object.values(webSocketPair); // 从 URL 或 headers 获取用户信息 const url = 新 URL(request.url); const userId = url.searchParams.get('userId') || '匿名的'; const 用户名 = url.searchParams.get('用户名') || '匿名的'; // 接受 WebSocket 并休眠 // 关键：使用 ctx.acceptWebSocket()，而不是 ws.accept() this.ctx.acceptWebSocket(服务器); // 序列化元数据以在休眠期间持续存在 const 元数据 = { userId, 用户名 }; server.serializeAttachment（元数据）； // 内存中的轨迹（休眠后将恢复） this.sessions.set（服务器，元数据）； // 通知其他人 this.broadcast(`${用户名} 加入`, 服务器); // 将客户端WebSocket返回给浏览器返回新的响应（空，{ 状态：101， webSocket：客户端， }); } // 当WebSocket收到消息时调用 async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise { const 会话 = this.sessions.get(ws); if (消息类型 === '字符串') { const data = JSON.parse(消息); if (data.type === '聊天') { // 向所有连接广播 this.broadcast(`${session?.username}: ${data.text}`, ws); } } } // WebSocket 关闭时调用 async webSocketClose(ws: WebSocket, 代码: 数字, 原因: 字符串, wasClean: 布尔值): Promise { const 会话 = this.sessions.get(ws); this.sessions.delete(ws); // 关闭WebSocket ws.close(code, '持久对象关闭 WebSocket'); // 通知其他人如果（会话）{ this.broadcast(`${session.username} left`); } } // 在 WebSocket 错误时调用异步 webSocketError(ws: WebSocket, 错误: 任何): Promise { console.error('WebSocket 错误：', error); const 会话 = this.sessions.get(ws); this.sessions.delete(ws); } // 向所有连接广播的助手广播（消息：字符串，除了？：WebSocket）：void { this.sessions.forEach((会话, ws) => { if (ws !== except && ws.readyState === WebSocket.OPEN) { ws.send(JSON.stringify({ type: 'message', text: message })); } }); } } **WebSocket 处理程序方法：** // 接收客户端发来的消息异步 webSocketMessage( ws：WebSocket，消息：字符串|数组缓冲区 ): 承诺 { // 处理消息 } // WebSocket 被客户端关闭异步 webSocketClose( ws：WebSocket，代码：数字，原因：字符串， wasClean：布尔值 ): 承诺 { // 清理 } // 发生 WebSocket 错误异步 webSocketError( ws：WebSocket，错误：任何 ): 承诺 { // 处理错误 } **休眠安全模式：** // ✅ 正确：使用 ctx.acceptWebSocket （启用休眠） this.ctx.acceptWebSocket(服务器); // ❌ 错误：不要使用 ws.accept() （标准 API，无休眠）服务器.accept(); // ✅ 正确：在休眠期间保留元数据 server.serializeAttachment({ userId: '123', 用户名: 'Alice' }); // ✅ 正确：在构造函数中恢复元数据构造函数（ctx，env）{ 超级（ctx，环境）； ctx.getWebSockets().forEach((ws) => { const 元数据 = ws.deserializeAttachment(); this.sessions.set(ws, 元数据); }); } // ❌ 错误：不要使用 setTimeout/setInterval （防止休眠） setTimeout(() => { /* ... */ }, 1000); // ❌ 永远不要这样做 // ✅ 正确：对计划任务使用警报等待 this.ctx.storage.setAlarm(Date.now() + 60000); **当不发生休眠时：** * `setTimeout` 或 `setInterval` 回调待处理 * 正在进行的 `fetch()` 请求（等待 I/O） * 使用标准 WebSocket API（不是休眠 API） * 请求/事件仍在处理中 ** ** ## 警报 API - 计划任务 **警报 API** 允许持久对象安排自己在未来的特定时间醒来。 **用于：** 批处理、清理作业、提醒、定期任务、延迟操作 ### 基本警报模式从 'cloudflare:workers' 导入 { DurableObject }; 导出类 Batcher 扩展 DurableObject { 缓冲区：字符串[]；构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； ctx.blockConcurrencyWhile(async () => { // 从存储中恢复缓冲区 this.buffer = wait ctx.storage.get('buffer') || []； }); } 异步 addItem(item: string): Promise { this.buffer.push(item); 等待 this.ctx.storage.put('buffer', this.buffer); // 从现在起 10 秒安排闹钟（如果尚未设置） const currentAlarm = 等待 this.ctx.storage.getAlarm(); if (currentAlarm === null) { 等待 this.ctx.storage.setAlarm(Date.now() + 10000); } } // 警报触发时调用异步闹钟(alarmInfo: { retryCount: number; isRetry: boolean }): Promise { console.log(`警报已触发（重试次数：${alarmInfo.retryCount}）`); // 处理批次 if (this.buffer.length > 0) { 等待 this.processBatch(this.buffer); // 清除缓冲区 this.buffer = []; 等待 this.ctx.storage.put('buffer', []); } // 执行成功后自动删除报警 } 异步 processBatch(items: string[]): Promise { // 发送到外部API、写入数据库等 console.log(`正在处理 ${items.length} 个项目：`, items); } } **报警API方法：** // 设置在特定时间戳触发的警报等待 this.ctx.storage.setAlarm(Date.now() + 60000); // 60 秒后 // 设置闹钟在特定日期触发等待 this.ctx.storage.setAlarm(new Date('2025-12-31T23:59:59Z')); // 获取当前闹钟（如果没有设置则为空） const AlarmTime =等待this.ctx.storage.getAlarm(); // 删除闹钟等待 this.ctx.storage.deleteAlarm(); // 警报处理程序（警报触发时调用）异步闹钟(alarmInfo: { retryCount: number; isRetry: boolean }): Promise { // 做工作 } **报警行为：** * ✅ **保证至少执行一次** \- 失败时将重试 * ✅ **自动重试** \- 最多 6 次重试，具有指数退避（从 2 秒开始） * ✅ **持久** \- 在 DO 冬眠和驱逐中幸存下来 * ✅ **执行成功后自动删除** * ⚠️ **每个 DO 一个警报** \- 设置新警报会覆盖前一个警报 **重试模式（幂等操作）：** 异步闹钟(alarmInfo: { retryCount: number; isRetry: boolean }): Promise { if (alarmInfo.retryCount > 3) { console.error('重试3次报警失败，放弃'); 返回; } 尝试{ // 幂等操作（可以安全重试）等待 this.sendNotification(); } 捕获（错误）{ console.error('报警失败：', error); 抛出错误； // 会触发重试 } } ** ** ## RPC 与 HTTP 获取持久对象支持**两种调用模式**： 1. **RPC（远程过程调用）** \- 推荐用于新项目 2. **HTTP Fetch** \- 用于 HTTP 请求/响应流或旧版兼容性 ### RPC 模式（推荐） **启用 RPC**，兼容日期 `>= 2024-04-03`： { “兼容性日期”：“2025-10-22” } **在 DO 类上定义 RPC 方法**：导出类 Counter 扩展 DurableObject { // 公共 RPC 方法（自动公开）异步增量(): Promise { let value = wait this.ctx.storage.get('count') || 0; 值+=1；等待 this.ctx.storage.put('count', value); 返回值； } 异步减量(): Promise { let value = wait this.ctx.storage.get('count') || 0; 值-= 1；等待 this.ctx.storage.put('count', value); 返回值； } 异步 get(): Promise { 返回等待 this.ctx.storage.get('count') || 0; } } **工人打来的电话：** // 获取存根 const id = env.COUNTER.idFromName('my-counter'); const 存根 = env.COUNTER.get(id); // 直接调用RPC方法 const count =等待存根.increment(); const current = wait Stub.get(); **RPC 的好处：** * ✅ **类型安全** \- TypeScript 知道方法签名 * ✅ **简单** \- 直接方法调用，无需 HTTP 仪式 * ✅ **自动序列化** \- 处理结构化数据 * ✅ **异常传播** \- DO 中抛出的错误在 Worker 中接收 ### HTTP 获取模式 **在 DO 类上定义 `fetch()` 处理程序**：导出类 Counter 扩展 DurableObject { 异步获取（请求：请求）：Promise { const url = 新 URL(request.url); if (url.pathname === '/increment' && request.method === 'POST') { let value = wait this.ctx.storage.get('count') || 0; 值+=1；等待 this.ctx.storage.put('count', value); 返回新的 Response(JSON.stringify({ count: value })); } if (url.pathname === '/get' && request.method === 'GET') { let value = wait this.ctx.storage.get('count') || 0; 返回新的 Response(JSON.stringify({ count: value })); } return new Response('未找到', { status: 404 }); } } **工人打来的电话：** // 获取存根 const id = env.COUNTER.idFromName('my-counter'); const 存根 = env.COUNTER.get(id); // 调用获取 constresponse=awaitstub.fetch('https://fake-host/increment', { 方法：'POST'， }); const data =等待response.json(); ### 何时使用每个使用案例|推荐 ---|--- **新项目** | ✅ RPC（更简单，类型安全） **HTTP 请求/响应流程** | HTTP 获取 **复杂的路由逻辑** | HTTP 获取 **类型安全很重要** | ✅ 远程过程调用 **旧版兼容性** | HTTP 获取 **WebSocket 升级** | HTTP 获取（必需） ** ** ## 创建持久对象存根和路由要与 Worker 中的持久对象交互，您需要： 1. 获取**持久对象 ID** 2. 根据 ID 创建 **存根** 3. 调用存根上的方法 ### 获取持久对象 ID **创建ID的三种方法：** #### 1\. `idFromName(name)` \- 命名 DO（最常见）当您希望基于名称对同一 DO 实例进行**一致的路由**时使用： // 相同的名称始终全局路由到相同的 DO 实例 const roomId = env.CHAT_ROOM.idFromName('room-123'); const userId = env.USER_SESSION.idFromName('user-alice'); const globalCounter = env.COUNTER.idFromName('global'); **用于：** * 聊天室（名称=房间ID） * 用户会话（名称=用户ID） * 每租户逻辑（名称 = 租户 ID） * 全局单例（name = 'global'） **特点：** * ✅ **确定性** \- 相同的名称 = 相同的 DO 实例 * ✅ **易于引用** \- 只需要名称字符串 * ⚠️ **首次访问延迟** \- ~100-300ms 用于全局唯一性检查 * ⚠️ **首次使用后缓存** \-后续访问很快 #### 2\. `newUniqueId()` \- 随机 ID 当您需要 **新的、唯一的 DO 实例** 时使用： // 创建一个随机的、全局唯一的 ID const id = env.MY_DO.newUniqueId(); // 有管辖权限制（欧盟数据驻留） const euId = env.MY_DO.newUniqueId({ 管辖范围: 'eu' }); // 保存ID以备将来使用 const idString = id.toString(); 等待 env.KV.put('会话:123', idString); **用于：** * 创建尚不存在的新会话/房间 * 一次性使用DO * 当你没有自然名字时 **特点：** * ✅ **首次使用时延迟较低**（无全局唯一性检查） * ⚠️ **必须存储 ID** 才能稍后访问相同的 DO * ⚠️ **ID 格式不透明** \- 无法从中得出含义 #### 3\. `idFromString(idString)` \- 从保存的 ID 重新创建当您**之前存储了 ID** 并且需要重新创建它时使用： // 获取存储的ID字符串（来自KV、D1、cookie等） const idString = wait env.KV.get('会话：123'); // 重新创建ID const id = env.MY_DO.idFromString(idString); // 获取存根 const 存根 = env.MY_DO.get(id); **抛出异常**如果： * ID 字符串无效 * ID 不是从相同的 `DurableObjectNamespace` 创建的 ### 获取存根 #### 方法 1：`get(id)` \- 来自 ID const id = env.MY_DO.idFromName('my-instance'); const 存根 = env.MY_DO.get(id); // 调用方法等待存根.myMethod(); #### 方法 2：`getByName(name)` \- 命名 DO 的快捷方式 // 结合 idFromName + get 的快捷方式 const 存根 = env.MY_DO.getByName('my-instance'); // 相当于： // const id = env.MY_DO.idFromName('my-instance'); // const 存根 = env.MY_DO.get(id); 等待存根.myMethod(); **推荐**用于命名 DO（更清晰的代码）。 ### 位置提示（地理路由） **使用位置提示控制持久对象的创建位置**： // 在特定位置附近创建 DO const id = env.MY_DO.idFromName('用户-alice'); const 存根 = env.MY_DO.get(id, { locationHint: 'enam' }); // 北美东部 // 可用位置提示： // - 'wnam' - 北美西部 // - 'enam' - 北美东部 // - 'sam' - 南美洲 // - 'weur' - 西欧 // - 'eeur' - 东欧 // - 'apac' - 亚太地区 // - 'oc' - 大洋洲 // - 'afr' - 非洲 // - '我' - 中东 **何时使用：** * ✅ 在用户位置附近创建 DO（较低延迟） * ✅ 数据驻留要求（例如，欧盟用户 → weur/eeur） **限制：** * ⚠️ **提示是尽力而为** \- 不保证 * ⚠️ **仅影响第一次创建** \-后续访问使用现有位置 * ⚠️ **无法移动现有的 DO** \- 一旦创建，位置就固定 ### 管辖权限制（数据驻留） **执行严格的数据位置**要求： // 创建必须留在欧盟的 DO const euId = env.MY_DO.newUniqueId({ 管辖范围: 'eu' }); // 可用司法管辖区： // - 'eu' - 欧盟 // - 'fedramp' - FedRAMP（美国政府） **用于：** * 监管合规性（GDPR、FedRAMP） * 数据主权要求 **关键：** * ✅ **严格执行** \- DO 永远不会离开管辖权 * ⚠️ **无法将**管辖权与位置提示结合起来 * ⚠️ **对于管辖范围之外的用户而言，延迟较高** ** ** ## 迁移 - 管理 DO 类 **当您满足以下条件时，需要迁移**： * 创建一个新的DO类 * 重命名DO类 * 删除DO类 * 将 DO 类转移给另一个 Worker **迁移类型：** ### 1\.创建新的 DO 类 { “耐用对象”：{ “绑定”：[ { “名称”：“计数器”， "class_name": "计数器" } ] }, “迁移”：[ { "tag": "v1", // 本次迁移的唯一标识符 "new_sqlite_classes": [ // SQLite 后端（推荐） “柜台” ] } ] } **对于 KV 后端（旧版）：** { “迁移”：[ { “标签”：“v1”， "new_classes": ["Counter"] // KV 后端（128MB 限制） } ] } **关键：** * ✅ 使用 `new_sqlite_classes` 来创建新的 DO（最多 1GB 存储空间） * ❌ 无法在现有部署的 KV 支持的 DO 上启用 SQLite ### 2\.重命名 DO 类 { “耐用对象”：{ “绑定”：[ { “姓名”：“MY_DO”， "class_name": "NewClassName" // 新类名 } ] }, “迁移”：[ { “标签”：“v1”， “new_sqlite_classes”：[“OldClassName”] }, { "tag": "v2", // 新的迁移标签 “重命名的类”：[ { "from": "OldClassName", "to": "新类名" } ] } ] } **发生了什么：** * ✅ 现有的 DO 实例保留其数据 * ✅ 旧绑定自动转发到新类 * ⚠️ **必须在 Worker 代码中导出新类** ### 3\.删除 DO 类 { “迁移”：[ { “标签”：“v1”， “new_sqlite_classes”：[“计数器”] }, { “标签”：“v2”， "deleted_classes": ["Counter"] // 标记为已删除 } ] } **发生了什么：** * ✅ 现有 DO 实例**立即删除** * ✅ 所有存储都被删除 * ⚠️ **无法撤消** \- 数据永久丢失 **删除前：** * 如果需要导出数据 * 更新引用此 DO 的 Worker ### 4\.将 DO 类转移给另一个 Worker // 在目标 Worker 中： { “耐用对象”：{ “绑定”：[ { “名称”：“TRANSFERRED_DO”， "class_name": "转移的班级" } ] }, “迁移”：[ { “标签”：“v1”， “转移的类”：[ { "from": "原始类", "from_script": "original-worker", // 源Worker名称 "to": "转班级" } ] } ] } **发生了什么：** * ✅ DO 实例移动到新的 Worker * ✅ 所有存储均已转移 * ✅ 旧绑定自动转发 * ⚠️ **必须导出目标类** ### 迁移规则 **关键迁移问题：** ❌ **迁移是原子的** \- 无法逐步部署 * 部署时所有实例都会立即迁移 * 不支持部分推出 ❌ **迁移标签必须是唯一的** * 不能重复使用标签 * 标签只能附加 ❌ **无法在现有 KV 支持的 DO 上启用 SQLite** * 必须创建新的 DO 类 ✅ **代码更改不需要迁移** * 只有架构更改（新建/重命名/删除/转移）需要迁移 * 可以自由部署代码更新 ✅ **全球唯一性是每个帐户** * DO 类名称在您的整个帐户中是唯一的 * 即使跨不同的 Worker ** ** ## 常见模式 ### 模式 1：速率限制（每用户）导出类 RateLimiter 扩展 DurableObject { async checkLimit(userId: string, limit: number, window: number): Promise { const key = `费率：${userId}`; const now = Date.now(); // 获取最近的请求 const requests = wait this.ctx.storage.get(key) || []； // 删除窗口外的请求 const validRequests = requests.filter(timestamp => now - timestamp < window); // 检查限制 if (validRequests.length >= limit) { 返回假； // 超出速率限制 } // 添加当前请求 validRequests.push(now); 等待 this.ctx.storage.put(key, validRequests); 返回真； // 在限制范围内 } } // 工人使用情况： const 限制器 = env.RATE_LIMITER.getByName(userId); const allowed = wait limiter.checkLimit(userId, 100, 60000); // 100 请求/分钟如果（！允许）{ return new Response('超出速率限制', { status: 429 }); } ### 模式 2：会话管理导出类 UserSession 扩展 DurableObject { sql：SqlStorage；构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sql = ctx.storage.sql; 这个.sql.exec(` 如果不存在则创建表会话（键文本主键，值文本不为空，到期日 INTEGER ）； `); // 安排清理警报 ctx.blockConcurrencyWhile(async () => { const 警报 = 等待 ctx.storage.getAlarm(); 如果（警报===空）{ 等待 ctx.storage.setAlarm(Date.now() + 3600000); // 1 小时 } }); } 异步集（键：字符串，值：任意，ttl？：数字）：Promise { const 过期时间 = ttl ? Date.now() + ttl : null; 这个.sql.exec( '插入或替换会话（键、值、expires_at）值（？、？、？）'，钥匙， JSON.stringify(值), 过期时间）； } 异步 get(key: string): Promise { const 游标 = this.sql.exec( '选择值，expires_at FROM 会话 WHERE key = ?', 钥匙）； const row = 游标.one<{ 值: 字符串;过期时间：数字 | null }>({ allowedNone: true }); 如果（！行）{ 返回空值； } // 检查过期时间 if (row.expires_at && row.expires_at < Date.now()) { this.sql.exec('从会话中删除 WHERE key = ?', key); 返回空值； } 返回 JSON.parse(row.value); } 异步闹钟(): Promise { // 清理过期会话 this.sql.exec('从会话中删除expires_at < ?', Date.now()); // 安排下一次清理等待 this.ctx.storage.setAlarm(Date.now() + 3600000); } } ### 模式3：领导者选举导出类 LeaderElection 扩展 DurableObject { sql：SqlStorage；构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sql = ctx.storage.sql; 这个.sql.exec(` 如果不存在则创建表领导者（ id 整数主键检查（id = 1）， worker_id 文本不为空， selected_at INTEGER NOT NULL ）； `); } async electLeader(workerId: string): Promise { // 尝试成为领导者尝试{ 这个.sql.exec( '插入领导者（id，worker_id，elected_at）值（1，？，？）'，工人ID，日期.now() ）；返回真； // 成为领导者 } 捕获（错误）{ 返回假； // 其他人是领导者 } } 异步 getLeader(): Promise { const 游标 = this.sql.exec('从领导者中选择worker_id WHERE id = 1'); const row=cursor.one<{worker_id: string }>({allowNone: true }); 返回行？.worker_id ||无效的; } 异步releaseLeadership（workerId：字符串）：Promise { this.sql.exec('从领导者那里删除 id = 1 AND worker_id = ?',workerId); } } ### 模式 4：多 DO 协调 // 协调器 DO 导出类 GameCoordinator 扩展 DurableObject { async createGame(gameId: string, env: Env): Promise { // 创建游戏房间 DO const gameRoom = env.GAME_ROOM.getByName(gameId); 等待 gameRoom.initialize(); // 跟踪协调器等待 this.ctx.storage.put(`游戏:${gameId}`, { id: 游戏ID, 创建：Date.now(), }); } 异步 listGames(): Promise { const games = wait this.ctx.storage.list({ prefix: 'game:' }); return Array.from(games.keys()).map(key => key.replace('游戏:', '')); } } // 游戏室DO 导出类 GameRoom 扩展 DurableObject { 异步初始化(): Promise { 等待 this.ctx.storage.put('状态', { 玩家：[]，开始：假， }); } async addPlayer(playerId: string): Promise { const state = wait this.ctx.storage.get('state'); state.players.push(playerId); 等待 this.ctx.storage.put('state', state); } } ** ** ## 关键规则 ### 总是这样做 ✅ **从 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 在空闲期之前完成 ** ** ## 配置参考 ### 完整的 wrangler.jsonc 示例 { "$schema": "node_modules/wrangler/config-schema.json", “姓名”：“我的工人”， "main": "src/index.ts", “兼容性日期”：“2025-10-22”， // 持久对象配置 “耐用对象”：{ “绑定”：[ { "name": "COUNTER", // 绑定名称（用作 env.COUNTER） "class_name": "Counter" // 必须匹配导出的类 }, { “名称”：“CHAT_ROOM”， "class_name": "聊天室" } ] }, // 迁移（所有 DO 更改都需要） “迁移”：[ { "tag": "v1", // 初始迁移 “new_sqlite_classes”：[ “柜台”， “聊天室” ] }, { "tag": "v2", // 重命名示例 “重命名的类”：[ { “来自”：“计数器”， “至”：“计数器V2” } ] } ] } ** ** ## TypeScript 类型从 'cloudflare:workers' 导入 { DurableObject, DurableObjectState, DurableObjectNamespace }; // 环境绑定接口环境{ MY_DO: DurableObjectNamespace; DB：D1数据库； // ...其他绑定 } // 持久对象类导出类 MyDurableObject 扩展 DurableObject { sql：SqlStorage；构造函数（ctx：DurableObjectState，env：Env）{ 超级（ctx，环境）； this.sql = ctx.storage.sql; } 异步 myMethod(): Promise { // 访问环境绑定等待 this.env.DB.prepare('...').run(); 返回“你好”； } } ** ** ## 官方文档 * **持久对象**： * **状态 API (SQL)** ： * **WebSocket 休眠** ： * **警报 API** ： * **迁移** ： * **最佳实践**： * **定价** ： ** ** **有问题吗？有问题吗？** 1. 检查 `references/top-errors.md` 常见问题 2. 查看“templates/”以获取工作示例 3.查阅官方文档： 4. 仔细验证迁移配置

Cloudflare 耐用对象

包含技能