durable-objects

durable-objects 技能總覽

durable-objects 的用途

durable-objects 技能可協助你建立並檢視 Cloudflare Durable Objects，用於在邊緣端處理有狀態的後端工作。當你需要處理簡單無狀態 Workers 無法乾淨完成的協調問題時，它特別合適：聊天室、多人遊戲連線、預約流程、每位使用者的狀態、RPC 處理器、alarms、WebSockets，或分片策略。

適合誰安裝

如果你正在使用 Cloudflare Workers 開發，並希望獲得關於物件設計、wrangler 設定、SQLite 支援儲存，以及測試設定的實務指引，就適合安裝 durable-objects 技能。對於後端開發工作尤其有用，因為這類工作正確性取決於狀態隔離、並行行為與部署接線。

它的差異在哪裡

這份 durable-objects 指南不只是語法說明。它會結合 Cloudflare 文件與 repo 參考資料，讓你在實作前先驗證 API、設定與最佳做法。這一點很重要，因為 Durable Objects 的細節會變動；這個技能的目的就是降低你沿用過時假設的風險。

如何使用 durable-objects 技能

先安裝，再按正確順序閱讀

先依照你的環境使用 durable-objects 的安裝路徑，接著從 SKILL.md 與 references/ 底下的參考檔案開始。建議先讀 references/rules.md、references/workers.md，以及 references/testing.md。這些檔案對應的是主要決策點：何時該用 DO、如何把它接到 Workers、以及如何測試。

給這個技能一個具體任務

durable-objects 的使用效果最好在你提供明確目標時，而不是模糊需求。好的輸入會包含物件邊界、儲存需求與執行路徑。例如：「為每個聊天室設計一個 Durable Object，使用 SQLite 儲存、WebSocket fanout，並為新的 SQLite 類別建立一條 Wrangler migration。」這樣技能才能選對模式，而不是靠猜。

把模糊意圖轉成可執行的提示詞

如果你手上只有功能想法，可以把它整理成四個部分：協調單位、操作內容、儲存模型，以及部署目標。例子：「我需要一個 Durable Object 來處理預約會話，負責保留時段、將狀態存到 SQLite、提供 RPC 方法，並在 Cloudflare Workers 上執行。請顯示 Wrangler bindings 和測試方式。」這會比單純問「給我一個 Durable Objects 範例」有效得多。

先檢查會影響輸出品質的檔案

在開始寫實作之前，先讀會影響行為的檔案：references/rules.md 看分片與儲存規則，references/workers.md 看 bindings 與 migrations，references/testing.md 看 Vitest 設定。如果你是在審查既有程式碼，也可以把這些檔案當成檢查清單，逐項對照你的實作。

durable-objects 技能 FAQ

durable-objects 只適合新專案嗎？

不是。durable-objects 技能不只適合從零開始的新建專案，也適合檢視或重構既有的 Cloudflare Workers 程式碼。當系統在開發環境能運作，但狀態邊界不清楚、migration 有缺口，或測試覆蓋很脆弱時，它特別有價值。

什麼情況下不該用 durable-objects？

如果你的應用不需要有狀態的協調，就不該用它。若請求可以用無狀態方式處理，或狀態應該放在獨立資料庫、KV 或 queue 裡，Durable Objects 反而可能增加不必要的複雜度。durable-objects 指南最適合的是：單一邏輯實體必須序列化工作，或必須擁有一個小而一致的狀態面。

這比一般提示詞更好嗎？

通常對 Cloudflare 特定工作來說是的。一般提示詞可能也能產出看起來合理的程式碼，但 durable-objects 技能是針對 wrangler 設定、物件命名、migration tag、RPC 模式，以及 Workers 執行環境中的測試而設計。這能降低漏掉部署細節的機率。

這適合初學者嗎？

適合，但前提是你已經知道自己在解決什麼問題。初學者通常最能從一次只請求一個有範圍的 Durable Object 設計開始，再在第一輪之後延伸到 migrations、測試與重構。

如何改進 durable-objects 技能

先指定協調邊界

最大的品質提升來自先定義一個 Durable Object instance 代表什麼。與其說「一個狀態層」，不如直接說「一個房間」、「一個會話」或「一個租戶」。清楚的邊界有助於分片、隔離失敗，也能避免意外形成瓶頸。

加入儲存、並行與執行環境限制

durable-objects 用於後端開發的工作流程，當你明確說出是否需要 SQLite、alarms、WebSockets、RPC，或 parent-child objects 時，效果會更好。也要補充限制，例如延遲敏感度、多區域考量，或這個物件是否必須透過 migrations 承受重新部署。

要求你真正需要的產物

如果你要的是程式碼，就說清楚你需要的是 class skeleton、Wrangler config、test file，還是 review checklist。如果你要的是審查，請提供目前的 wrangler.toml、object class，以及任何 tests。輸出類型越具體，之後需要收拾的內容就越少。

從一個實作迭代到一個測試

拿到第一版輸出後，先測最薄弱的部分：binding names、migration tags、method signatures，或 state isolation。如果結果接近但還不完整，就針對單一問題要求修訂，例如「改成 SQLite storage」或「加入 @cloudflare/vitest-pool-workers 測試以驗證 concurrent access」。