Cloudflare Workers compatibility_date 怎麼升：先盤點 flags，再更新日期
Cloudflare Workers 的 compatibility_date 不是註解，也不是單純記錄部署日期。它是 Worker 採用相容性變更的基準；同一份程式碼在不同日期下，可能因平台行為不同而表現不同。
直接做法是：先找出目前設定與相關 compatibility flags，再在可測試的環境更新日期，最後才部署 production。不要把日期直接改成今天，卻沒有看過該版本差異。
日期在哪裡設定
Wrangler 設定檔可用 JSON 或 TOML 指定：
{ "name": "example-worker", "main": "src/index.ts", "compatibility_date": "2026-07-29"}新建 Worker 時，Dashboard 會自動使用建立當日作為 compatibility date。但若透過 Workers Script API 或 Workers Versions API 上傳而未指定日期，Cloudflare 文件說明會回到最早的基準日期（2021-11-02、在任何 flags 生效之前）。因此自動化部署不應把這個欄位留給預設值。
為什麼舊日期需要主動盤點
Workers 文件通常描述目前的預設行為；舊 Worker 仍可能保留歷史行為。要理解落差，應從 compatibility flags 找「你的目前日期」到「準備更新的日期」之間的變更，而不是只看某一段最新文件。
我會先記下三個項目：
wrangler.jsonc或wrangler.toml的既有compatibility_date。- 有沒有明確的
compatibility_flags，以及它們是否仍為暫時性 workaround。 - Worker 依賴的平台行為：request/response、Node.js compatibility、bindings、Durable Objects 或 scheduled handler。
這份盤點能避免兩種相反的錯誤：以為新日期必然需要所有新 flag，或以為已有 flag 就代表可以永久不升級。
一個較安全的升級順序
把升級當成程式行為變更，而不是格式化設定檔：
# 1. 固定目前設定，先在 branch 或 preview 環境修改日期pnpm testpnpm build
# 2. 檢查 Wrangler 會使用的設定，再部署到非正式環境npx wrangler deploy --dry-run--dry-run 適合檢查部署輸入，但不能取代實際 request 測試。接著應對 preview URL 跑最小的 smoke test，例如健康檢查、需要 binding 的 endpoint、失敗回應與 cron handler。
| 檢查面向 | 要確認的事 |
|---|---|
| HTTP 行為 | status、headers、redirect 與串流回應是否仍符合預期 |
| bindings | KV、R2、D1、Durable Objects 與 secrets 是否在正確環境可用 |
| Node 相容性 | 是否依賴特定 Node API 或既有 compatibility flag |
| rollback | 上一個可用版本與設定是否可立即恢復 |
如果某項行為只有在特定 flag 下成立，將 flag 與原因寫在設定旁或變更紀錄；日後清理時才知道它是否仍必要。
日期與帳號選擇是兩件事
更新日期不會保護你免於部署到錯的帳號。本機多帳號情境仍應用 profile 與 account_id 做部署前確認，可參考 Wrangler auth profiles 的多帳號防呆。反過來說，選對帳號也不代表升級了 Worker 行為；兩項檢查都應放在部署流程。
參考資料：
回報錯字、失效連結，或告訴我你想看的延伸主題。