Cloudflare Durable Objects 的設定改成「宣告式」：用 exports 取代要一步步記錄的 migrations

一句話看懂：Cloudflare 讓 Durable Objects 的設定從「按順序記錄每一步遷移」改成「直接宣告現在有哪些類別」，少維護一長串歷史標籤。

先用白話講：這個設定在管什麼？

Durable Objects 是 Cloudflare Workers 上的有狀態物件，可以想成「每個都有專屬儲存櫃的小管理員」。當你要新增、改名或刪掉一種管理員（程式裡的一個類別），Cloudflare 必須知道線上那些儲存櫃該怎麼處理，不然資料就可能對不上。

過去的做法像是寫日記：v1 新增了 ChatRoom，v2 把 ChatRoom 改名為 Room，每一步都要記下來、編上唯一的標籤，而且順序不能亂。專案越老，日記越長。

新的做法比較像貼一張「現況表」：直接寫出「現在有哪些類別、各自是什麼狀態」，Cloudflare 自己去和線上已部署的內容比對，決定要建立、改名或刪除。

發生什麼事

Cloudflare 在 2026 年 7 月 4 日的更新日誌宣布，Wrangler 設定檔新增宣告式的 exports 欄位，取代命令式的 migrations 陣列。依官方說明，好處有四個：

• 不需要遷移標籤：現在的 exports 清單就是唯一事實來源，不必維護 v1、v2、v3 的歷史鏈
• 部署輸出更結構化：Wrangler 會回報建立、更新、刪除、改名或轉移了哪些類別，也會指出可以安全移除的過時設定；沒有變更時不會印出多餘訊息
• 零停機的改名與轉移：墓碑（tombstone）狀態可以和原本還在程式碼裡的類別並存，讓改名用三次部署、跨 Worker 轉移用四次部署，推出期間不會出現執行期錯誤
• 跨 Worker 保護：刪除或改名類別時，Cloudflare 會列出帳號內所有仍綁定該命名空間的其他 Worker，讓你先重新部署它們

新舊寫法對照

要把 ChatRoom 改名為 Room，兩種寫法的差別：

// 舊：migrations，兩個有標籤的步驟都要保留
{
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
    { "tag": "v2", "renamed_classes": [{ "from": "ChatRoom", "to": "Room" }] }
  ]
}

// 新：exports，宣告現況
{
  "exports": {
    "ChatRoom": { "type": "durable-object", "state": "renamed", "renamed_to": "Room" },
    "Room": { "type": "durable-object", "storage": "sqlite" }
  }
}

每一筆以類別名稱當索引鍵。state 欄位表示生命週期：預設是「created」（仍在使用的類別），另外有 deleted、renamed、transferred 三種墓碑狀態，以及跨 Worker 轉移時接收端用的 expecting-transfer 狀態。

給開發者的技術細節

• 使用 migrations 的既有 Worker 不受影響，會照常運作
• exports 與 migrations 在單一 Worker 內互斥，不能同時寫
• 要從舊寫法搬到新寫法，請看官方的遷移指南；完整欄位說明在官方的「Durable Object class exports」文件

我的看法

如果你的 Workers 專案已經有 Durable Objects，可以注意這個更新，但不用急著動。舊寫法官方明講會繼續運作，貿然搬遷反而多一個風險點。我的建議是：新專案直接用 exports，舊專案等下次要改名或轉移類別時，再順便搬。

它最大的價值在「改名」這種高風險操作：Durable Objects 的資料綁在類別上，改錯就可能找不到資料。有了跨 Worker 的檢查，以及三次部署的零停機流程，等於把容易出錯的步驟流程化了。只是這個流程要分好幾次部署，還是得在測試環境先演練一遍。

名詞小辭典

• Wrangler：Cloudflare Workers 的官方命令列工具，設定檔也在這裡。
• Durable Object 類別：定義這種有狀態物件長什麼樣子、能做什麼的程式碼。
• 宣告式 vs 命令式：宣告式是描述「我要什麼結果」，命令式是列出「要一步步做什麼」。
• 墓碑（Tombstone）狀態：標記某個類別已刪除、改名或轉移的紀錄，讓系統知道它的後續處理。

資料來源

• Cloudflare 更新日誌：Declare Durable Object class lifecycle with exports（2026-07-04）