Cloudflare Durable Objects 中文文档

参照官方手册结构整理（数据截至 2026-10，配额/价格以官方最新页面为准）。技术术语保留英文原词。

1. 概述

Durable Objects（DO） 是 Cloudflare 的一种特殊 Worker，把计算与存储打包在一起，用于构建**有状态（stateful）**的无服务器应用。

一句话定位：强一致、带持久存储的状态协调原语——每个对象有全局唯一名字，可作为多个客户端的协调点。

Free 与 Paid 计划均可用。SQLite 存储后端已 GA，且在 Free 计划即可使用。

2. 核心概念

• 全局唯一名字：每个 Durable Object 有唯一名，可从世界任何地方向特定对象发请求，用于多客户端协调（聊天、协作、游戏、实时通知）。
• 持久存储：存储与对象在一起，因此强一致且访问快。
• 单线程：单个对象本质单线程，单对象软上限约 1,000 请求/秒；可水平扩展出无限个对象。
• SQLite 后端（推荐）：用 sql.exec 等 Storage API 做事务化、强一致、可序列化的存储。
• Alarms：可设定在未来某时刻触发对象执行计算（定时任务）。
• WebSocket Hibernation：以极低开销管理大量客户端长连接。

3. 架构与工作原理

DO 像 Worker 一样就近自动部署、按需启动、空闲关闭，全球可有数百万个。但不同于普通 Worker：每个对象有名字 + 持久存储，因此能协调状态。DO 是 Worker 脚本，继承 Workers 的调用级 CPU 限制。

4. 快速开始（SQLite 后端）

wrangler.jsonc 配置类与绑定：

{
  "durable_objects": {
    "bindings": [{ "name": "CHAT", "class_name": "ChatRoom" }]
  },
  "migrations": [{ "tag": "v1", "new_classes": ["ChatRoom"] }]
}

import { DurableObject } from "cloudflare:workers";

export class ChatRoom extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const stmt = this.ctx.storage.sql.exec("SELECT count(*) FROM messages");
    return Response.json(stmt.one());
  }
}

5. 配额与限制（SQLite 后端）

SQL 限制与 D1 相同：每表列 ≤ 100、单行 ≤ 2 MB、SQL 长度 ≤ 100 KB、绑定参数 ≤ 100。

6. 定价

• 免费日限额每日 00:00 UTC 重置；超免费额直接报错，需升级 Paid。
• 单对象存储满（Free 1 GB / Paid 10 GB）后写入失败（SQLITE_FULL），但读与删除仍可用。

7. 最佳实践

• 用对象名做分片/路由（如 room:123），把协调粒度降到单对象。
• 用 SQLite 后端替代旧 KV 后端（Free 仅支持 SQLite 后端）。
• 单对象别做过多 list()，会拉低吞吐；必要时拆更多对象。
• 需要高频定时任务用 Alarms，而非轮询。

8. 适用场景与选型

• 多客户端协调：协作编辑、聊天、多人游戏、实时通知、AI Agent 状态。
• 需要强一致的计数/锁/会话 → 选 DO（而不是最终一致的 KV）。
• 简单全局小配置、读多写少 → KV 更轻；关系型 SQL 查询 → D1；大文件 → R2。