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 就代表可以永久不升級。
2026-08-04 後，Node.js compatibility 會跟著日期啟用
Cloudflare 在 2026-08-04 的 Workers 更新中說明：compatibility_date 為 2026-08-04 或更新的 Worker，會預設啟用 nodejs_compat 與 nodejs_compat_v2 的行為。這表示 node:crypto、node:buffer、node:stream 等 Workers 支援的 Node.js 內建 API，會隨日期一起進入執行環境；較早日期的 Worker 不會因為這項更新自動改變。
因此升級日期時，不能只檢查「我有沒有手寫 nodejs_compat」。還要問兩件事：
- 專案是否依賴某個 Node.js API 或套件在新相容性行為下的輸出？
- 目前明確寫在
compatibility_flags的 flag，是必要設定、暫時 workaround，還是已經被新日期涵蓋？
對於使用 Hyperdrive、Node.js database driver 或其他 Node.js 相依套件的 Worker，先保留明確的 flag，再用測試證明可以移除，不要因為新日期已經涵蓋它就順手刪掉。需要連接 MySQL 的設定範例，可參考 Cloudflare Hyperdrive 的 mysql2 連線流程。
如果你的目標是完全關閉 Node.js compatibility，官方提供的方向不是只刪除 nodejs_compat，而是移除 nodejs_compat／nodejs_compat_v2 後，同時加入兩個 opt-out flag：
{ "compatibility_date": "2026-08-20", "compatibility_flags": [ "no_nodejs_compat", "no_nodejs_compat_v2" ]}這是行為選擇，不是升級的清理步驟。只有在確認 bundle、測試與 production request 都不需要 Node.js compatibility 時，才應採用這個設定。
一個較安全的升級順序
把升級當成程式行為變更，而不是格式化設定檔：
# 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 行為；兩項檢查都應放在部署流程。
參考資料：
Cloudflare Workers Docs：Compatibility dates
Cloudflare Workers Docs：Compatibility flags
Cloudflare Changelog：Node.js compatibility is now enabled by default
回報錯字、失效連結，或告訴我你想看的延伸主題。