Durable Objects 的 exports lifecycle：何時該從 migrations 轉換

它把歷史步驟改成目前狀態#

假設舊的 ChatRoom 要改名為 Room。傳統設定需要保留每一次 tagged migration：

1
{
2
  "migrations": [
3
    { "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
4
    { "tag": "v2", "renamed_classes": [{ "from": "ChatRoom", "to": "Room" }] }
5
  ]
6
}

exports 則直接描述現在的 class，並保留舊 class 作為 rename tombstone：

1
{
2
  "exports": {
3
    "ChatRoom": {
4
      "type": "durable-object",
5
      "state": "renamed",
6
      "renamed_to": "Room"
7
    },
8
    "Room": { "type": "durable-object", "storage": "sqlite" }
9
  }
10
}

Cloudflare 會比對這份 map 與已部署狀態，決定要建立、重新命名、刪除或轉移哪些 class。它也會在部署輸出中報告 lifecycle 改動與可移除的 stale 設定。

轉換前先盤點，別先改設定檔#

我會先整理這些問題：

1. 每個 Durable Object 的現有 class 名稱、namespace 與 storage backend 是什麼？
2. 程式碼、其他 Worker bindings 或部署流程，是否還引用舊 class？
3. 這次是純粹改管理方式，還是真的要 rename、delete 或 cross-Worker transfer？
4. 是否已讀過 exports 的 lifecycle 狀態與部署輸出，並在非正式環境跑過一次？

官方文件指出，created 是 live class 的預設狀態；另外還有 deleted、renamed、transferred 等 tombstone 狀態，以及接收跨 Worker transfer 的 expecting-transfer。不要自行把 tombstone 刪掉來「清理設定」：它是 lifecycle 紀錄的一部分。

rename 與 transfer 的 rollout 不是一次 deploy 就結束#

exports 讓 zero-downtime rename 和 transfer 成為一等模式，但仍需要多次部署。在 rollout 期間，tombstone 可以與程式碼中原 class 並存，讓舊 binding 與新 class 有過渡空間。若有其他 Worker 綁定相同 namespace，Cloudflare 也會列出仍引用它們的 Worker，讓你先重新部署相依服務。

這不是資料庫 schema migration 工具：它只管理 class lifecycle。若你的需求是將既有 KV-backed Durable Object 改成 SQLite，請先分開處理；新 namespace 的 SQLite 限制與 storage backend 遷移，是另一個需要資料備份與切流策略的問題。可參考 SQLite 與 exports 的 storage 邊界。

最小上線檢查清單#

• wrangler.jsonc 只保留 exports 或 migrations 其中一種。
• 每個 live class 和 tombstone 的用途都能對應目前或歷史 namespace。
• rename／transfer 已依官方步驟規劃多次 deploy，而不是一次性抽換名稱。
• 先檢查 deployment output，確認沒有意外的 delete、rename 或跨 Worker 影響。
• 既有 Worker 若沒有實際維護痛點，可繼續使用 migrations，不必為了新語法冒遷移風險。

exports 的價值是把 Durable Object lifecycle 的「目前真相」變得可讀；轉換的安全關鍵則是先理解你已經部署過的歷史。

參考資料：

Cloudflare Changelog：Workers 更新紀錄（2026-07-04 exports lifecycle）

Cloudflare Docs：Durable Object class exports