Cloudflare Wrangler.jsonc中已删除Durable Objects的处理疑问

问题背景 #

用户当前的wrangler.jsonc配置如下：

// wrangler.jsonc
{
  "name": "hono-do-1", // Replace with your desired worker name if needed
  "main": "src/index.ts",   // Entry point for your worker
  "compatibility_date": "2024-04-05", // Use a recent compatibility date
  // Define the Durable Objects binding
  "durable_objects": {
    "bindings": [
      // `name`: The variable name used in your Worker code (Env interface) to access the DO namespace.
      // `class_name`: The name of the exported class that implements the Durable Object.
      // `script_name` (optional): Specifies which worker script exports the class. Defaults to the current worker.
      { "name": "STATUS_TIMES_DO", "class_name": "StatusTimes" } // <-- Add this binding
    ]
  },
  // Define migrations for the Durable Object using the SQLite backend (required for free tier)
  "migrations": [
    {
      "tag": "v1", // A unique identifier for this migration set
      // Use new_sqlite_classes instead of new_classes for the free tier
      "new_sqlite_classes": ["Counter"] // <-- Only Counter in v1
    },
    {
      "tag": "v2", // New tag for StatusTimes
      "new_sqlite_classes": ["StatusTimes"] // <-- Only StatusTimes in v2
    },
    {
      "tag": "v3", // New tag for StatusTimes
      "deleted_classes": ["Counter"] // <-- Delete Counter in v3
    }
  ]
}

用户先创建了测试用的Counter Durable Object，之后添加StatusTimes，移除所有Counter的代码引用后，尝试删除配置中的v1和v3迁移标签，部署时出现报错：

14:54:29.652     ⛅️ wrangler 4.22.0 (update available 4.31.0)
14:54:29.652    ─────────────────────────────────────────────
14:54:32.942    ▲ [WARNING] The published script hono-do-1 has a migration tag "v3, which was not found in your wrangler.json file. You may have already deleted it. Applying all available migrations to the script...
14:54:32.943    
14:54:32.943    
14:54:32.969    Total Upload: 402.44 KiB / gzip: 74.38 KiB
14:54:33.997    Your Worker has access to the following bindings:
14:54:33.997    Binding                                Resource            
14:54:33.998    env.STATUS_TIMES_DO (StatusTimes)      Durable Object      
14:54:33.998    
14:54:33.999    
14:54:34.000    ✘ [ERROR] A request to the Cloudflare API (/accounts/bdaab8a54502652762d78b31c5dfb1ef/workers/scripts/hono-do-1) failed.
14:54:34.001    
14:54:34.001      Cannot apply new-sqlite-class migration to class 'StatusTimes' that is already depended on by existing Durable Objects [code: 10074]
14:54:34.001      
14:54:34.001      If you think this is a bug, please open an issue at: https://github.com/cloudflare/workers-sdk/issues/new/choose
14:54:34.001    

用户疑问：是否需要永久保留v1和v3这两个迁移标签？

回答 #

不需要永久保留v1和v3标签，但不能直接删除，得按以下步骤操作：

报错原因 #

Cloudflare的迁移系统会跟踪所有已应用的迁移标签，当你直接删除v1和v3后，配置里只剩v2，Wrangler会误认为需要重新执行v2的迁移——也就是再次创建StatusTimes类，但这个类已经存在于系统中，因此触发Cannot apply new-sqlite-class migration的报错。

正确清理步骤 #

1. 确认当前部署状态：确保当前线上版本已经应用了v3迁移（即Counter已被删除），保持现有migrations数组不变，重新部署一次确认无异常。
2. 添加空的新迁移标签：在migrations数组末尾新增一个标签（比如v4），不需要添加或删除任何类，仅用来标记当前的最终状态：

{
  "tag": "v4",
  "new_sqlite_classes": [],
  "deleted_classes": []
}

3. 部署新版本：使用更新后的配置部署，确保成功。此时Cloudflare系统会记录v4已被应用。
4. 安全删除旧迁移条目：现在可以删除v1、v2、v3的迁移条目，只保留v4（甚至可以只保留一个空的migrations数组，不过保留最新标签更清晰）。再次部署即可正常完成。

内容的提问来源于stack exchange，提问作者ELECTRON