Cloudflare 在 2026 年 11 月 17 日發布 cf CLI 1.0.0-rc.1,從 9 月底開始的 beta 進入 1.0 release candidate。官方表示,cloudflare.config.ts、Build Output 格式,以及 cf init、cf dev、cf build、cf deploy、preview deploy 與 Worker version 建立等主要流程,預期會維持到 1.0;但少數由 Cloudflare API schema 產生的命令路徑仍可能調整。

RC 代表介面接近穩定,不等於所有 production 專案應立刻從 Wrangler 全面切換。這次最需要處理的是已在 beta 使用 cf、把它放進 CI 腳本,或準備以 cloudflare.config.ts 建立新專案的團隊。現有 Wrangler 專案可以先維持原本工具,建立相容性測試;不要在沒有回滾的情況下,同時換 CLI、設定格式、Build Output 與部署權限。

RC 升級有四類明確相容性變更

第一類是 Build Output。RC 把輸出移到 .cloudflare/output/v1/;第一次以新版本部署時,cf deploy 會在新位置重建。若 CI cache、artifact upload、掃描工具或自訂腳本仍固定讀取舊路徑,部署本身可能成功,後續步驟卻找不到檔案。升級前應搜尋 .cloudflare/output 的硬編碼路徑,並讓 artifact schema 帶上版本。

第二類是依賴門檻。使用 Vite 的專案需要 @cloudflare/vite-plugin 2.0.0-rc.0 以上;由 Wrangler 支援舊專案的流程需要 Wrangler 4.163.0 以上。不要只更新全域 cf,卻讓 lockfile 保留不相容的 plugin 或 Wrangler。CI 應從 lockfile 安裝固定版本,避免開發機成功、乾淨 runner 失敗。

第三類是命令名稱。1.0.0-rc.1 有部分產生命令沒有提供舊 alias,例如 cf workers secrets bulk 改為 cf workers secrets bulk-edit;release note 也列出 email routing 與其他 bulk 命令改名。先在 repository、部署平台與內部 runbook 搜尋 cf ,逐項用 --help 或 cf cli search 核對,不要用猜測的字串全域替換。

第四類是腳本輸出與狀態。beta 期間已把 prompt、progress、status 寫到 stderr,stdout 只保留命令輸出;preview name、local state 位置、帳號選擇與 streaming tail consumer 設定也曾改動。若腳本用 stdout 關鍵字判斷成功、依賴上次互動選過的 account,或把 stderr 一律當失敗,就需要調整。

cf 與 Wrangler 不是單純的新舊版本關係

cf 的方向是涵蓋 Cloudflare API 與 Workers 專案的統一 CLI,命令多數由公開 OpenAPI surface 產生,預設 JSON 介面也適合自動化與 agent。cloudflare.config.ts 可用型別化的 TypeScript 設定 Worker、Container 與 account 相關值;RC 文件提醒,大多數 cf 命令會讀取目前目錄往上的最近一份設定,因此執行位置也屬於部署輸入。

Wrangler 已有成熟的 Workers 生態、既有 wrangler.toml/JSONC 設定與大量 production 腳本。對穩定運行的舊專案,保留 Wrangler、先在非正式環境試用 cf,通常比一次改完風險低。對新專案,cf 的 Build Output、Vite 整合與 API command search 值得評估,但 RC 仍應固定版本,不能用無上限的 latest 直接驅動 production。

兩套工具可以在遷移期共存,但要指定單一部署權威。若 CI 用 Wrangler、開發者又用 cf deploy 修改遠端設定,容易出現 drift;cf deploy --force 雖能處理部分遠端衝突,卻不應成為日常掩蓋差異的開關。應清楚定義哪個 job 可發布、設定來源在哪裡,以及誰能使用帶破壞性的 --force。

安全的 beta 升級流程

先建立 inventory:記錄目前 cf、Wrangler、Vite plugin、Node.js 與 package manager 版本,列出所有 cf 命令、環境變數、設定檔、Build Output 讀取者和 Cloudflare account。接著在分支上固定 RC 版本與相容依賴,清除舊輸出後執行 cf build,比對 .cloudflare/output/v1/ 的 Worker、static assets、bindings 與 source map 是否符合預期。

第二階段用測試 account 或獨立 Worker 驗證。至少包含本機開發、preview、version 建立、正式格式的 deploy、secret 更新、log tail 與回滾;先用 read-only 或最小權限命令確認 account,再執行寫入。不要用 production secret 當測試資料,也不要因 RC 新增安全確認就把所有命令一律加上 --force。

第三階段檢查自動化介面。分別擷取 exit code、stdout 與 stderr,確認 JSON parser 只讀 stdout,log collector 仍收得到進度,而 warning 不會被誤判為部署成功。非互動 runner 應明確設定 accountId 或 CLOUDFLARE_ACCOUNT_ID;多 account 使用者不能依賴 CLI 記住上次選擇。

正式切換時保留前一版 lockfile、設定與部署命令,先從低流量服務 canary。驗收不只看 HTTP 200,還要核對 routes、bindings、secrets、cron、static assets、observability 與回滾版本。若新 Build Output 或命令改名造成問題,回滾應恢復整組相容版本與原部署流程,而不是只降全域 CLI。

cf 1.0 RC 的價值在於統一設定、API 操作與部署介面,也提供 cf observability tail 等新能力;它同時把過去 beta 的路徑與命令調整集中到一次升級檢查。新專案可以把 RC 納入試點,既有專案則以可重現 build、最小權限與雙路徑驗收為切換條件,等確認工具鏈而非只確認版本號後再擴大採用。