Cloudflare Durable Objects 配置實戰指南wrangler.jsonc 綁定、數據本地化與遷移機制全解【免費下載鏈接】skillsSkills Catalog for Codex項目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以本倉庫 cloudflare-deploy skill 中的 Durable Objects 配置文檔 為核心骨架結合同目錄下的 README、API、Patterns、Gotchas 以及 DO Storage 文檔 縱深展開。讀完本文你將掌握如何在wrangler.jsonc中正確聲明 Durable Object 綁定與遷移、如何通過 Binding Options 訪問其他 Worker 中的 DO、如何利用 Jurisdiction 滿足歐盟數據駐留與 FedRAMP 合規、如何為 staging/production 隔離命名空間以及npx wrangler durable-objects系列管理命令的完整用法。一、Durable Objects 是什么為什么需要一份專門的配置文檔Durable ObjectsDO將「計算」與「存儲」打包成全局唯一、強一致的單元每個 DO 實例擁有全局唯一 ID、與計算同地的強一致存儲、自動就近放置、內存態加持久化存儲的雙層狀態并且以單線程方式串行處理請求天然無競態。它正是構建狀態協調、實時協同、計數、會話、限流等有狀態應用的平臺基座。正因為 DO 是有狀態的它的聲明與配置遠不止一個main入口那么簡單你需要在wrangler.jsonc中完成綁定聲明、遷移策略、環境隔離、計算限額等一整套配置。本文討論的 configuration.md 正是這套配置的完整權威說明下面逐節展開。二、基本配置在 wrangler.jsonc 中聲明 Durable ObjectDO 的配置入口是 Worker 項目根目錄下的wrangler.jsonc或wrangler.toml。核心配置項包括頂層durable_objects與migrations兩個塊完整示例如下{ name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, // Use latest; ≥2024-04-03 for RPC durable_objects: { bindings: [ { name: MY_DO, // Env binding name class_name: MyDO // Class exported from this worker }, { name: EXTERNAL, // Access DO from another worker class_name: ExternalDO, script_name: other-worker } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyDO] } // Prefer SQLite ] }逐項拆解name/mainWorker 名稱與入口文件與普通 Worker 配置一致。compatibility_date建議始終使用最新日期。特別地若要在 Worker 側以 RPC 方式直調 DO 方法而不是走fetch()compatibility_date必須≥ 2024-04-03否則 RPC 不可用只能退回fetch()調用見下文「RPC 與 fetch() 的選擇」。durable_objects.bindings數組每項聲明一個綁定。name是注入env的綁定名如env.MY_DOclass_name是該 Worker 內導出的 DO 類名。示例中第二個綁定通過script_name指向另一個 Workerother-worker導出的ExternalDO類實現跨 Worker 訪問。migrations聲明 DO 類如何隨版本演進創建、重命名、遷移、刪除。注意其中new_sqlite_classes明確標記了「優先使用 SQLite 后端」這是當前官方推薦的存儲選擇。存儲后端的選擇SQLite 與 KV 的取舍new_sqlite_classes與new_classes分別對應兩種 DO 存儲后端差異見 DO Storage 概覽后端創建方式可用 API30 天時間點恢復PITRSQLite推薦new_sqlite_classesSQL 同步 KV 異步 KV?KV遺留new_classes僅異步 KV?從源碼結構看DO Storage 文檔 將 SQLite 定位為推薦后端它支持結構化數據、關系查詢與事務單實例存儲上限 10GB而 KV 后端只能使用異步 KV API也不支持時間點恢復。因此新項目一律使用new_sqlite_classes。三、Binding Options綁定項的完整參數單個綁定項的完整可配置字段如下{ name: BINDING_NAME, class_name: ClassName, script_name: other-worker, // Optional: external DO environment: production // Optional: isolate by env }name注入env的綁定標識符Worker 代碼中通過env.name拿到DurableObjectNamespace。class_name實際處理邏輯的 DO 類名必須與源碼中export class導出的類名一致。script_name可選。省略時表示 DO 類由當前 Worker 導出填寫另一個 Worker 名稱時當前 Worker 可以訪問那個 Worker 導出的 DO 類即「外部 DO」用于跨服務共享有狀態協調單元。environment可選。配合env塊做環境隔離時使用讓同一綁定在不同環境staging/production指向相互獨立的對象命名空間詳見第六節。四、Jurisdiction數據本地化從 ID 創建那一刻鎖定數據邊界對于 GDPR、FedRAMP 等合規要求DO 支持在「創建 ID」時指定司法轄區jurisdiction從而保證該 DO 實例的物理位置、存儲與計算全部落在指定邊界內。核心示例// EU data residency const id env.MY_DO.idFromName(user:123, { jurisdiction: eu }) // Available jurisdictions const jurisdictions [eu, fedramp] // More may be added // All operations on this DO stay within jurisdiction const stub env.MY_DO.get(id) await stub.someMethod() // Data stays in EU關鍵要點務必牢記在 ID 創建時設置創建后不可變更jurisdiction是 ID 的屬性idFromName/newUniqueId一旦返回 ID其轄區即已固定之后無法修改。如果后續需要遷轄區只能換用新 ID 重建。物理位置保證DO 實例的物理部署位置、存儲與計算均被限定在指定轄區邊界內。強隔離語義不存在跨轄區訪問——如果請求訪問的 DO 位于不同轄區調用會直接失敗。因此設計時必須確保創建 ID 與訪問 ID 的代碼使用一致的 jurisdiction 參數。從 README 的 ID 生成策略看三種 ID 生成方式各有定位idFromName()生成確定性 ID適合命名協調限流、分布式鎖newUniqueId()生成隨機 ID適合分片高吞吐負載idFromString()則從既有 ID 字符串反推 ID 對象。Jurisdiction 選項可以疊加在這三種方式之上使用。五、MigrationsDO 類隨版本演進的生命周期管理DO 類的增刪改不能只改代碼必須通過migrations顯式聲明否則部署時 Wrangler 無法知道如何處理既有實例。完整示例{ migrations: [ { tag: v1, new_sqlite_classes: [MyDO] }, // Create SQLite (recommended) // { tag: v1, new_classes: [MyDO] }, // Create KV (paid only) { tag: v2, renamed_classes: [{ from: Old, to: New }] }, { tag: v3, transferred_classes: [{ from: Src, from_script: old, to: Dest }] }, { tag: v4, deleted_classes: [Obsolete] } // Destroys ALL data! ] }每種遷移動作的語義new_sqlite_classes新建使用 SQLite 后端的 DO 類推薦。new_classes新建使用 KV 后端的 DO 類注意該操作僅限付費賬戶。renamed_classes將舊類Old重命名為New實例與數據隨類名遷移。transferred_classes把類Src可指定其來源腳本from_script遷移到目標類Dest適合跨腳本/跨類轉移數據而無需刪除。deleted_classes刪除類。??立即銷毀該類的所有 DO 實例與全部數據不可逆若只是轉移而非清除應使用transferred_classes。遷移規則違反即部署失敗tag 必須唯一且嚴格遞增v1, v2, v3...依次排列不允許跳號或重復。這也是 gotchas.md 中「Migration Failed (Deploy error)」最常見的原因。不支持回滾一旦部署應用了遷移無法回退。上線前務必用npx wrangler deploy --dry-run驗證遷移合法性。部署時自動應用npx wrangler deploy會先檢查 migrations 數組把未應用的新條目按順序應用到線上。優先new_sqlite_classes除非有明確理由新類一律走 SQLitenew_classes僅限付費賬戶且失去 PITR 能力。deleted_classes立即且不可逆地銷毀全部數據需要保留數據的任何移動都優先考慮renamed_classes/transferred_classes。從 DO Storage 文檔 可知SQLite 后端還附帶 30 天時間點恢復PITR能力可作為高風險遷移前的「后悔藥」——不過它只恢復存儲數據不撤銷遷移元數據因此核心防線仍然是--dry-run預檢。六、環境隔離為 staging/production 建立獨立的 DO 命名空間DO 實例天然與「綁定 環境」綁定。如果你在 staging 與 production 共用同一綁定二者會讀到同一批 DO 實例這在有狀態應用中是不可接受的。正確做法是借助env塊為每個環境覆蓋durable_objects配置{ durable_objects: { bindings: [{ name: MY_DO, class_name: MyDO }] }, env: { production: { durable_objects: { bindings: [ { name: MY_DO, class_name: MyDO, environment: production } ] } } } }要點頂層durable_objects是默認本地開發/未指定環境時的綁定聲明。env.production塊內的綁定額外指定了environment: production。該字段將 DO 類放入獨立的命名空間從而讓生產環境的 DO 實例與 staging/默認環境的實例完全隔離——兩邊的對象互不可見、數據互不干擾。部署到該環境使用npx wrangler deploy --env production。這也印證了第三節的environment字段用途它是「環境隔離」的開關配合env配置塊實現按環境分命名空間。七、Limits Settings調整 CPU 時間上限DO 單次請求默認有 30 秒 CPU 時間限制超限會被終止。可通過limits.cpu_ms調高{ limits: { cpu_ms: 300000 // Max CPU time: 30s default, 300s max } }默認值30 秒30000 ms。最大值300 秒300000 ms即示例中的取值。適用場景確需長時間計算的任務對于超長任務更穩妥的策略是切分工作并使用 Alarm 分片處理而不是一味調高上限。完整限制表見 gotchas.md其中與配置直接相關的關鍵限額包括限額項Free / Paid說明單 DO SQLite 存儲10 GB按實例計SQLite 總存儲5 GB / 不限賬戶級配額單 KV 鍵值大小2 MBSQLite/異步 KV 均適用CPU 時間默認/最大30s / 300s通過limits.cpu_ms設置DO 類數量100 / 500不同的 DO 類定義數單表 SQL 列數100每表SQL 語句大小100 KB單條查詢上限WebSocket 消息大小32 MiB單條消息單 DO 吞吐~1K req/s軟限制超出需分片單 DO Alarm 數1多事件需隊列模式單 DO 內存128 MB內存態 WebSocket 緩沖八、TypeScript 類型DurableObjectNamespace 的正確用法配置完成后代碼側需要類型化的綁定聲明。推薦寫法import { DurableObject } from cloudflare:workers; interface Env { MY_DO: DurableObjectNamespaceMyDO; } export class MyDO extends DurableObjectEnv {} type DurableObjectNamespaceT { newUniqueId(options?: { jurisdiction?: string }): DurableObjectId; idFromName(name: string): DurableObjectId; idFromString(id: string): DurableObjectId; get(id: DurableObjectId): DurableObjectStubT; };要點DO 類繼承自cloudflare:workers導出的DurableObjectEnv基類構造函數接收DurableObjectState封裝 storage、WebSockets、alarms與Env各綁定。DurableObjectNamespaceT是env.MY_DO的類型newUniqueId生成隨機 ID可攜帶jurisdiction選項idFromName生成確定性 IDidFromString從字符串還原 IDget(id)返回指向該實例的DurableObjectStubT隨后即可直調類上導出的 RPC 方法。從 api.md 可見DO 類內部可同時實現 RPC 方法Worker 直接調用、fetch()處理器HTTP 語義/代理/遺留兼容以及生命周期處理器alarm、webSocketMessage、webSocketClose、webSocketError。RPC 與 fetch() 的選擇配置層面的連帶決策選擇調用方式與compatibility_date直接相關RPC推薦新項目要求compatibility_date ≥ 2024-04-03。類型安全、寫法更簡單const count await stub.increment()。fetch()遺留/特殊場景需要 HTTP 語義讀寫 header、狀態碼、需要把請求代理轉發給 DO、或需要兼容舊項目時使用const count await (await stub.fetch(req)).json()。這個決策應在配置階段就定下因為它決定了你的compatibility_date取值與代碼寫法。九、常用命令從本地開發到線上管理開發npx wrangler dev # Local dev npx wrangler dev --remote # Test against production DOswrangler dev在本地Miniflare運行 Worker 與 DO加--remote則直接聯通云端真實 DO用于驗證線上綁定與遷移后的行為。部署npx wrangler deploy # Deploy auto-apply migrations npx wrangler deploy --dry-run # Validate migrations without deploying npx wrangler deploy --env production--dry-run是遷移安全的核心防線它只做校驗tag 唯一/順序、類名有效性等而不真正上線是第五節「不支持回滾」的補償手段。--env production對應第六節的環境隔離部署。管理npx wrangler durable-objects list # List namespaces npx wrangler durable-objects info namespace id # Inspect specific DO npx wrangler durable-objects delete namespace id # Delete DO (destroys data)list列出當前賬戶/環境下的 DO 命名空間。info namespace id查看指定 DO 實例的元數據與狀態。delete namespace id刪除指定實例——該操作銷毀數據與deleted_classes遷移同樣不可逆務必確認 ID 后再執行。從 SKILL.md 可知執行任何wrangler deploy類命令前應先npx wrangler whoami確認已認證在沙箱環境中若部署網絡調用被阻斷需要以sandbox_permissionsrequire_escalated重跑。十、配置之外的實戰要點讓配置真正落地配置正確只是第一步結合同目錄文檔可將配置價值最大化構造函數每次喚醒都會執行冷啟動或被 Hibernation 喚醒均如此因此不要在構造函數里做重初始化采用懶加載模式。這是 gotchas.md 反復強調的性能關鍵點。Hibernation 會清空內存態所有關鍵數據必須寫入ctx.storageSQLite/同步 KV/異步 KV或使用ws.serializeAttachment()持久化連接級元數據不能依賴類字段。定時任務用setAlarm()而非setTimeout后者隨實例驅逐而丟失前者持久化存儲、可跨驅逐觸發且失敗會自動重試但非 exactly-once需冪等處理。單 DO 只有一個 Alarm需要多個定時事件時采用「事件隊列 單一 Alarm」模式——存入帶runAt的事件Alarm 觸發時掃描到期事件并重排最近的下一個觸發時間詳見 patterns.md。單 DO 吞吐約 1K req/s超過則用newUniqueId()或哈希把負載分片到多個 DO如按hash(userId) % 100分 100 片這是 patterns.md 給出的 Sharding 方案。競態防護DO 雖單線程但await是讓步點異步操作期間可能插入其他請求關鍵區段使用ctx.blockConcurrencyWhile()簡單計數優先用 SQL 原子語句INSERT ... ON CONFLICT DO UPDATE ... RETURNING代替「讀-改-寫」。高頻低延遲存儲用 SQLite SQL 與同步 KV從 DO Storage 文檔 的 API 劃分看SQLite 后端同時提供 SQL、同步 KVctx.storage.kv與異步 KVctx.storage三種接口同步接口免去await適合熱路徑。十一、快速上手一份可直接落地的完整配置示例把本文內容串起來一個帶 SQLite DO、環境隔離、CPU 限額的完整wrangler.jsonc如下{ name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, durable_objects: { bindings: [ { name: COUNTER, class_name: Counter } ] }, migrations: [ { tag: v1, new_sqlite_classes: [Counter] } ], limits: { cpu_ms: 300000 }, env: { production: { durable_objects: { bindings: [ { name: COUNTER, class_name: Counter, environment: production } ] } } } }// src/index.ts import { DurableObject } from cloudflare:workers; interface Env { COUNTER: DurableObjectNamespaceCounter; } export class Counter extends DurableObjectEnv { async increment(): Promisenumber { const result this.ctx.storage.sql.exec( INSERT INTO counters (id, value) VALUES (1, 1) ON CONFLICT(id) DO UPDATE SET value value 1 RETURNING value ).one(); return result.value; } } export default { async fetch(request: Request, env: Env): PromiseResponse { const id env.COUNTER.idFromName(global); const stub env.COUNTER.get(id); return new Response(Count: ${await stub.increment()}); } };本地npx wrangler dev驗證通過后npx wrangler deploy --dry-run預檢遷移再npx wrangler deploy上線生產環境使用npx wrangler deploy --env production。延伸閱讀Durable Objects 概覽與決策樹Durable Objects APIctx 方法、Alarm、WebSocket HibernationDurable Objects 實戰模式分片、限流、分布式鎖、會話、多事件隊列Durable Objects 常見坑與完整限額表DO Storage 深度指南SQLite / KV / PITR / 事務cloudflare-deploy skill 總覽與部署前置要求【免費下載鏈接】skillsSkills Catalog for Codex項目地址: https://gitcode.com/GitHub_Trending/skills4/skills創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考