前言¶
把项目部署到 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
