前言¶
把項目部署到 Cloudflare，聽起來只是一句「跑個 wrangler deploy」，實際動手時往往會卡在幾個地方：Workers 和 Pages 該選哪個？KV、D1、R2 這些存儲怎麼綁定？本地開發用 OAuth 登錄，CI 裏又該配什麼 Token？Cloudflare 產品線多、文檔分散，Agent 若缺少結構化指引，很容易在錯誤的產品分支上兜圈子。
cloudflare-deploy 是 OpenAI 在 openai/skills 倉庫 .curated 目錄下維護的 Agent Skill，面向「部署、託管、發佈、在 Cloudflare 上搭建項目」這類需求。與側重 Vercel 一鍵預覽部署的 vercel-deploy 相比，它覆蓋的是 Cloudflare 整站能力——Workers 邊緣函數、Pages 全棧站點、Durable Objects、R2 對象存儲、Workers AI 等，更像一本可按需翻頁的部署決策手冊。
本文基於官方 SKILL.md 及 references/ 子文檔覈實，介紹該 Skill 的定位、能力、安裝方式與典型用法。
這是什麼¶
cloudflare-deploy 是一個遵循 Agent Skills 開放標準（agentskills.io）的技能包，核心文件爲目錄下的 SKILL.md，並附帶大量 references/ 參考文檔，供 Agent 按場景按需加載。
官方描述如下：
Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
（通過 Workers、Pages 及相關平臺服務，將應用和基礎設施部署到 Cloudflare；當用戶要求部署、託管、發佈或在 Cloudflare 上搭建項目時使用。）
來源歸屬：OpenAI 維護的 openai/skills 精選（curated）技能目錄。該倉庫 README 標註已 deprecated，並指向 OpenAI Plugins 作爲 Codex 插件的新示例來源；但 cloudflare-deploy 仍可通過 GitHub 目錄或本地複製方式在 Cursor、Codex CLI 等支持 SKILL.md 的工具中使用。
它解決的核心問題：把 Cloudflare 龐雜的產品矩陣，整理成 Agent 可執行的決策樹與分產品參考文檔，減少「選錯產品、漏配鑑權、忽略沙箱網絡限制」等常見失誤。
核心功能與亮點¶
1. 決策樹：先選產品，再讀細節¶
Skill 正文不試圖一次塞滿所有 Cloudflare 文檔，而是用決策樹幫 Agent 快速定位：
需要運行代碼時，按場景分流：
- 邊緣 Serverless 函數 → Workers
- 帶 Git 部署的全棧 Web 應用 → Pages
- 有狀態協調 / 即時 → Durable Objects
- 長時多步驟任務 → Workflows
- 容器 → Containers
- 定時任務 → Cron Triggers
- 輕量 HTTP 改寫 → Snippets
需要存儲數據時：
- 鍵值（配置、會話、緩存）→ KV
- 關係型 SQL → D1（SQLite）或 Hyperdrive（已有 Postgres/MySQL）
- 對象 / 文件存儲 → R2
- 消息隊列 → Queues
- 向量嵌入 → Vectorize
此外還有 AI/ML、網絡連通、安全、媒體內容、基礎設施即代碼（Pulumi / Terraform / REST API）等分支。Agent 命中分支後，再去加載 references/ 下對應產品的 README 與配置說明。
2. 產品索引表：Compute、Storage、AI 一網打盡¶
SKILL.md 末尾附有完整 Product Index，涵蓋：
| 類別 | 代表產品 |
|---|---|
| 計算與運行時 | Workers、Pages、Durable Objects、Workflows、Containers |
| 存儲與數據 | KV、D1、R2、Queues、Hyperdrive、Secrets Store |
| AI 與機器學習 | Workers AI、Vectorize、Agents SDK、AI Gateway |
| 網絡與安全 | Tunnel、WAF、Turnstile、Bot Management |
| 開發者工具 | Wrangler、Miniflare、C3、Observability |
這種索引結構讓 Agent 在複雜需求（例如「Pages 函數 + D1 數據庫 + R2 靜態資源」）下，能分模塊查閱，而不是憑記憶硬寫配置。
3. 部署前置與鑑權流程寫死在 Skill 裏¶
與 vercel-deploy 強調「默認預覽部署」類似，cloudflare-deploy 把鑑權和沙箱網絡寫進 Prerequisites：
- 部署前必須先驗證 Cloudflare 登錄狀態
- 若 Agent 運行在沙箱環境且出站網絡被攔截，需使用
sandbox_permissions=require_escalated重試 - 部署可能耗時數分鐘，Agent 應設置足夠長的超時
4. 與 vercel-deploy 的對比視角¶
| 維度 | vercel-deploy | cloudflare-deploy |
|---|---|---|
| 平臺 | Vercel | Cloudflare |
| 範圍 | 以 CLI 部署爲主，含無鑑權 fallback 腳本 | 全平臺決策樹 + 分產品 reference |
| 默認策略 | 默認預覽部署，生產需用戶明確要求 | 按產品文檔執行，強調先 wrangler whoami |
| 典型命令 | vercel deploy -y |
wrangler deploy / wrangler pages deploy |
| 適用場景 | 前端 / 全棧快速上線預覽 | 邊緣計算、Serverless、多雲並存 |
若團隊同時使用 Vercel 與 Cloudflare，兩個 Skill 可以並列安裝，由 Agent 根據用戶意圖自動選擇。
安裝與啓用¶
Agent Skill 通用格式：每個技能是一個包含 SKILL.md 的文件夾，可選 scripts/、references/、assets/ 子目錄。
在 Codex CLI 中安裝¶
OpenAI 官方 README 說明，精選技能可通過 Codex 內置的 $skill-installer 按名稱安裝：
$skill-installer cloudflare-deploy
也可指定 GitHub 目錄 URL：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/cloudflare-deploy
安裝後需重啓 Codex 以加載新技能。
在 Cursor 中安裝¶
Cursor 會從以下目錄自動發現技能（官方文檔）：
| 路徑 | 作用域 |
|---|---|
.cursor/skills/ |
項目級 |
.agents/skills/ |
項目級 |
~/.cursor/skills/ |
用戶級（全局） |
~/.agents/skills/ |
用戶級（全局） |
手動安裝步驟：
- 克隆或下載 cloudflare-deploy 目錄
- 將整個
cloudflare-deploy文件夾放入上述任一 skills 目錄 - 重啓 Cursor，或在 Agent 對話中輸入
/搜索cloudflare-deploy手動調用
也可通過 Cursor 側邊欄 Customize → Rules → Add Rule → Remote Rule (Github) 導入 GitHub 倉庫鏈接。
兼容 Claude Code 等工具¶
Skills 遵循開放標準，.claude/skills/、~/.claude/skills/ 等目錄在 Cursor 中同樣會被加載；其他支持 Agent Skills 的工具可按各自文檔放置同名目錄結構。
典型用法示例¶
以下示例均來自官方 SKILL.md 與 references/wrangler/auth.md、references/workers/、references/pages/，可直接復現。
第一步：驗證 Cloudflare 鑑權¶
在執行 wrangler deploy、wrangler pages deploy 或 npm run deploy 之前，Agent 應運行：
npx wrangler whoami # 已登錄則顯示賬號信息
未登錄時的處理方式：
- 本地 / 交互環境：
npx wrangler login（一次性 OAuth，瀏覽器授權） - CI/CD / 無瀏覽器環境：設置環境變量
CLOUDFLARE_API_TOKEN（在 Cloudflare 控制檯創建 Token，推薦使用「Edit Cloudflare Workers」模板）
第二步：按需求選擇 Workers 或 Pages¶
部署邊緣 Worker（API、代理、WebSocket 等）：
npm create cloudflare@latest my-worker -- --type hello-world
cd my-worker
npx wrangler dev # 本地開發
npx wrangler deploy # 生產部署
Worker 推薦使用 Module 模式：
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
return new Response('Hello World!');
},
};
部署 Pages 靜態 / 全棧站點：
# 構建產物目錄部署
npx wrangler pages deploy ./dist --project-name=my-project
# 本地預覽
npx wrangler pages dev ./dist
Pages 也支持 Git 集成（Dashboard 連接 GitHub/GitLab 自動部署）和 C3 腳手架：
npm create cloudflare@latest my-app
第三步：Agent 對話中的觸發方式¶
當用戶說出類似以下意圖時，Agent 應自動匹配該 Skill：
- 「把這個項目部署到 Cloudflare」
- 「用 Workers 寫一個邊緣 API 並上線」
- 「Pages 怎麼綁定 D1 數據庫？」
- 「幫我在 Cloudflare 上託管這個靜態站點」
在 Cursor 中也可顯式輸入 /cloudflare-deploy 調用。
沙箱與網絡權限¶
若部署因超時、DNS 錯誤或連接重置失敗，官方 Troubleshooting 指引 Agent 使用提升的網絡權限重試，並向用戶說明：
The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?
（部署到 Cloudflare 需要提升的網絡訪問權限，是否授權重試？）
適用場景與注意事項¶
適合誰、什麼場景：
- 需要把 API、中間層邏輯跑在邊緣節點，降低全球用戶延遲
- 使用 Pages 託管 JAMstack / 框架項目（SvelteKit、Astro、Nuxt 等），並希望 Agent 理解 Git 部署與 Direct Upload 兩種方式
- 項目涉及 Cloudflare 存儲（KV、D1、R2）或 AI 能力（Workers AI、Vectorize），需要 Agent 按官方 reference 寫綁定配置
- 與 Vercel 並存的多雲部署流程，由不同 Skill 分工
限制與注意：
- Skill 體積大：
references/下文檔衆多，Agent 應漸進加載，避免一次塞滿上下文。 - 必須事先鑑權：Unlike vercel-deploy 提供的無鑑權 fallback 腳本，Cloudflare 部署依賴 Wrangler 登錄或 API Token，Agent 不應跳過
whoami檢查。 - 倉庫狀態：openai/skills 主倉庫已標註 deprecated，長期使用可關注 OpenAI Plugins 生態；當前 GitHub 目錄內容仍可複製使用。
- 部署耗時：構建與全球分發可能需數分鐘，Agent 命令需配置合理 timeout。
- 產品選型：Workers 偏 API / 複雜路由；Pages 偏靜態站點與框架 Git 工作流；二者可通過 Pages Functions 結合，Skill 內決策樹可幫助區分。
結尾¶
cloudflare-deploy 的價值，在於把 Cloudflare 從「邊緣 CDN 廠商」擴展爲「可編排的全棧平臺」這一事實，翻譯成了 Agent 能逐步執行的決策路徑：先鑑權，再選產品，再讀 reference，最後執行 Wrangler 命令。如果你已經在用 vercel-deploy 處理 Vercel 側的快速預覽，不妨把 cloudflare-deploy 一併裝上，讓 Agent 在 Serverless 與邊緣計算場景裏也有據可依。
官方目錄：https://github.com/openai/skills/tree/main/skills/.curated/cloudflare-deploy
