Cloudflare Durable Objects 指南：构建有状态边缘应用 | 协调、存储、实时处理

durable-objects by cloudflare/skills

2,700 周安装量

693 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/cloudflare/skills --skill durable-objects

开发云服务开发运维

🇨🇳中文介绍

Durable Objects

在 Cloudflare 边缘网络上构建有状态、可协调的应用程序。

检索来源

您对 Durable Objects API 和配置的了解可能已过时。对于任何 Durable Objects 任务，优先使用检索而非预训练。

资源	URL
文档	https://developers.cloudflare.com/durable-objects/
API 参考	https://developers.cloudflare.com/durable-objects/api/
最佳实践	https://developers.cloudflare.com/durable-objects/best-practices/
示例	https://developers.cloudflare.com/durable-objects/examples/

实现功能时，请获取相关的文档页面。

使用场景

为有状态协调创建新的 Durable Object 类
实现 RPC 方法、警报或 WebSocket 处理程序
审查现有 DO 代码以遵循最佳实践
为 DO 绑定和迁移配置 wrangler.jsonc/toml
使用 @cloudflare/vitest-pool-workers 编写测试

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

705,000 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

245,300 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

196,800 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

128,699 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

搜索：blockConcurrencyWhile、idFromName、getByName、setAlarm、sql.exec

需求	示例
协调	聊天室、多人游戏、协作文档
强一致性	库存系统、预订系统、回合制游戏
按实体存储	多租户 SaaS、用户数据
持久连接	WebSockets、实时通知
按实体调度工作	订阅续订、游戏超时

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DO: DurableObjectNamespace<MyDurableObject>;
}

export class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS items (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          data TEXT NOT NULL
        )
      `);
    });
  }

  async addItem(data: string): Promise<number> {
    const result = this.ctx.storage.sql.exec<{ id: number }>(
      "INSERT INTO items (data) VALUES (?) RETURNING id",
      data
    );
    return result.one().id;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.MY_DO.getByName("my-instance");
    const id = await stub.addItem("hello");
    return Response.json({ id });
  },
};

围绕协调原子建模 - 每个聊天室/游戏/用户一个 DO，而不是一个全局 DO
使用 getByName() 进行确定性路由 - 相同输入 = 相同 DO 实例
使用 SQLite 存储 - 在迁移中配置 new_sqlite_classes
在构造函数中初始化 - 仅将 blockConcurrencyWhile() 用于模式设置
使用 RPC 方法 - 而非 fetch() 处理程序（兼容性日期 >= 2024-04-03）
先持久化，后缓存 - 在更新内存状态之前，始终先写入存储
每个 DO 一个警报 - setAlarm() 会替换任何现有警报

单个全局 DO 处理所有请求（瓶颈）
在每个请求上都使用 blockConcurrencyWhile()（扼杀吞吐量）
仅将关键状态存储在内存中（驱逐/崩溃时丢失）
在相关的存储写入操作之间使用 await（破坏原子性）
在 fetch() 或外部 I/O 期间持有 blockConcurrencyWhile()

🇺🇸English

Durable Objects

Build stateful, coordinated applications on Cloudflare's edge using Durable Objects.

Retrieval Sources

Your knowledge of Durable Objects APIs and configuration may be outdated. Prefer retrieval over pre-training for any Durable Objects task.

Resource	URL
Docs	https://developers.cloudflare.com/durable-objects/
API Reference	https://developers.cloudflare.com/durable-objects/api/
Best Practices	https://developers.cloudflare.com/durable-objects/best-practices/
Examples	https://developers.cloudflare.com/durable-objects/examples/

Fetch the relevant doc page when implementing features.

When to Use

Creating new Durable Object classes for stateful coordination
Implementing RPC methods, alarms, or WebSocket handlers
Reviewing existing DO code for best practices
Configuring wrangler.jsonc/toml for DO bindings and migrations
Writing tests with @cloudflare/vitest-pool-workers
Designing sharding strategies and parent-child relationships

Reference Documentation

./references/rules.md - Core rules, storage, concurrency, RPC, alarms
./references/testing.md - Vitest setup, unit/integration tests, alarm testing
./references/workers.md - Workers handlers, types, wrangler config, observability

Search: blockConcurrencyWhile, idFromName, getByName, setAlarm, sql.exec

Core Principles

Use Durable Objects For

Need	Example
Coordination	Chat rooms, multiplayer games, collaborative docs
Strong consistency	Inventory, booking systems, turn-based games
Per-entity storage	Multi-tenant SaaS, per-user data
Persistent connections	WebSockets, real-time notifications
Scheduled work per entity	Subscription renewals, game timeouts

Do NOT Use For

Stateless request handling (use plain Workers)
Maximum global distribution needs
High fan-out independent requests

Quick Reference

Wrangler Configuration

// wrangler.jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
}

Basic Durable Object Pattern

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DO: DurableObjectNamespace<MyDurableObject>;
}

export class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS items (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          data TEXT NOT NULL
        )
      `);
    });
  }

  async addItem(data: string): Promise<number> {
    const result = this.ctx.storage.sql.exec<{ id: number }>(
      "INSERT INTO items (data) VALUES (?) RETURNING id",
      data
    );
    return result.one().id;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.MY_DO.getByName("my-instance");
    const id = await stub.addItem("hello");
    return Response.json({ id });
  },
};

Critical Rules

Model around coordination atoms - One DO per chat room/game/user, not one global DO
UsegetByName() for deterministic routing - Same input = same DO instance
Use SQLite storage - Configure new_sqlite_classes in migrations
Initialize in constructor - Use blockConcurrencyWhile() for schema setup only
Use RPC methods - Not fetch() handler (compatibility date >= 2024-04-03)
Persist first, cache second - Always write to storage before updating in-memory state
One alarm per DO - setAlarm() replaces any existing alarm

Anti-Patterns (NEVER)

Single global DO handling all requests (bottleneck)
Using blockConcurrencyWhile() on every request (kills throughput)
Storing critical state only in memory (lost on eviction/crash)
Using await between related storage writes (breaks atomicity)
Holding blockConcurrencyWhile() across fetch() or external I/O

Stub Creation

// Deterministic - preferred for most cases
const stub = env.MY_DO.getByName("room-123");

// From existing ID string
const id = env.MY_DO.idFromString(storedIdString);
const stub = env.MY_DO.get(id);

// New unique ID - store mapping externally
const id = env.MY_DO.newUniqueId();
const stub = env.MY_DO.get(id);

Storage Operations

// SQL (synchronous, recommended)
this.ctx.storage.sql.exec("INSERT INTO t (c) VALUES (?)", value);
const rows = this.ctx.storage.sql.exec<Row>("SELECT * FROM t").toArray();

// KV (async)
await this.ctx.storage.put("key", value);
const val = await this.ctx.storage.get<Type>("key");

Alarms

// Schedule (replaces existing)
await this.ctx.storage.setAlarm(Date.now() + 60_000);

// Handler
async alarm(): Promise<void> {
  // Process scheduled work
  // Optionally reschedule: await this.ctx.storage.setAlarm(...)
}

// Cancel
await this.ctx.storage.deleteAlarm();

Testing Quick Start

import { env } from "cloudflare:test";
import { describe, it, expect } from "vitest";

describe("MyDO", () => {
  it("should work", async () => {
    const stub = env.MY_DO.getByName("test");
    const result = await stub.addItem("test");
    expect(result).toBe(1);
  });
});

Weekly Installs

1.9K

Repository

cloudflare/skills

GitHub Stars

566

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode1.6K

codex1.6K

gemini-cli1.5K

github-copilot1.4K

amp1.3K

claude-code1.3K

Cloudflare Durable Objects 指南：构建有状态边缘应用 | 协调、存储、实时处理

🇨🇳中文介绍

Durable Objects

检索来源

使用场景

相关 Skills

参考文档

核心原则

Durable Objects 适用于

不适用于

快速参考

Wrangler 配置

基本 Durable Object 模式

关键规则

反模式（切勿使用）

Stub 创建

存储操作

警报

测试快速入门

🇺🇸English

Durable Objects

Retrieval Sources

When to Use

Reference Documentation

Core Principles

Use Durable Objects For

Do NOT Use For

Quick Reference

Wrangler Configuration

Basic Durable Object Pattern

Critical Rules

Anti-Patterns (NEVER)

Stub Creation

Storage Operations

Alarms

Testing Quick Start