觀點 · 資訊分享

Cloudflare Workflows 設定少一段：排程工作直接寫在 exports，Worker 自己就能叫用

Cloudflare 讓 Workflows 可以直接宣告在 Wrangler 設定檔的 exports 欄位，9 月 27 日起同一個 Worker 也能透過 ctx.exports 呼叫它，不必再為了「定義」和「呼叫」各寫一個 binding。

一句話看懂：Cloudflare Workflows 的設定變簡單了，背景流程直接寫在 exports 就能部署，同一個 Worker 也能直接叫用，不用再多寫一段 binding。

Workflows 可宣告在 exports資訊圖卡：Workflow 寫進 exports 就能部署，同一個 Worker 直接用 ctx.exports 叫用

先用白話講：Workflows 是什麼？

想像一張外送訂單：接單、通知店家、等餐點做好、派外送員、送達後寄收據。每一步都可能卡住，也可能要等好幾分鐘。

Cloudflare Workflows 就是幫你管這種「多步驟、要等很久」流程的服務。每一步失敗會自動重試，系統重啟也能從中斷的地方繼續，不必自己寫一堆狀態紀錄。

以前有個小麻煩：就算只是想「定義」一個 Workflow，也必須在設定檔加一個 binding（綁定），等於同一件事要寫兩次。

Cloudflare 開發者更新日誌分兩次公布：

9 月 24 日：Workflows 可以直接宣告在 Wrangler 設定檔的 exports 欄位，不必再加 workflows binding
9 月 27 日：定義這個 Workflow 的 Worker，可以透過 ctx.exports 直接呼叫它，用法和 binding 一樣

另外兩個重點：

新專案：可以直接用 exports 寫法，設定檔裡只需要描述一次 Workflow，部署時一起建立
既有專案：不需要改，binding 寫法繼續有效；想整理設定時，可以逐一把 Workflow 從 binding 搬到 exports
跨 Worker 呼叫：如果是 A Worker 要呼叫 B Worker 定義的 Workflow，仍然要用 binding，這次的 ctx.exports 只適用於同一個 Worker 內部
測試流程：用 Vitest 寫測試的團隊要留意，部分檢查工具還是需要 binding，測試設定可能要另外補一段

簡單說，這次是把「自己定義、自己使用」這種最常見的情境變簡單，其他情境維持原樣。

設定檔寫法（依官方範例改寫）：

{
  "exports": {
    "ReportWorkflow": {
      "type": "workflow",
      "name": "report-workflow",
      "schedules": ["0 0 * * *"]
    }
  }
}

在 Worker 裡直接叫用：

const instance = await ctx.exports.ReportWorkflow.create({
  params: { name: "World" },
});

版本與限制：

需求	版本
在 exports 宣告 Workflow	Wrangler 4.139.0 以上
本機開發用 ctx.exports	Wrangler 4.142.0、Vite 外掛 1.61.0、Vitest 外掛 1.3.0 以上

這是一個很小、但很實用的改動。在 Cloudflare 上做排程或背景工作時，binding 名稱和類別名稱對不上是很常見的錯誤，往往部署後才發現叫不到。現在定義和呼叫都收在 exports 一個地方，設定檔清爽很多。

對已經在跑的專案，不需要急著改；官方也保證同名的 binding 和 export 會共用執行個體，真的要搬時可以一次搬一個，風險不大。新專案就可以直接用新寫法。

Cloudflare Workflows 是什麼？

Cloudflare 上用來跑「多步驟、可能要等很久」背景工作的服務，例如每天產報表、下單後依序寄信與對帳。每一步都會自動重試，失敗也能從中斷的地方繼續。

我現有的 workflows binding 要改嗎？

不用。binding 照常可用，兩種寫法也能並存；只要兩邊用同一個類別、設定值不衝突就好。

exports 裡可以設定哪些東西？

和 workflows binding 一樣，可以設定 limits（例如步驟上限）、schedules（排程）與 default_retention，執行 wrangler deploy 時會一起建立或更新。

測試時有什麼要注意？

在 Vitest 裡，introspectWorkflow() 和 introspectWorkflowInstance() 仍然需要 Workflow binding；要檢查宣告在 exports 的 Workflow，官方建議加一個只給測試用的 binding。

作者

接案做系統開發、網站與主機託管。觀點裡的文章都是我自己寫的,寫的是做專案時第一手遇到的事。