前言¶
在 Cloudflare 上做边缘计算，日常离不开 Wrangler：本地 wrangler dev、上线 wrangler deploy，以及 KV、R2、D1 等资源的创建与绑定。命令多、配置字段也在持续更新，AI 编程助手如果只靠训练时的旧知识，很容易写出过时的 flag、错误的 binding 形状，甚至把本该用交互式输入的密钥写进命令行参数。
Cloudflare 官方仓库 cloudflare/skills 里提供了一个名为 wrangler 的 Agent Skill。它不是替代 Wrangler CLI 本身，而是一套在执行相关任务前加载的操作指引：要求助手先核对官方文档与本地配置 schema，再按当前最佳实践生成命令与 wrangler.jsonc。
这是什么¶
wrangler 是 Cloudflare 维护的 Agent Skill（SKILL.md 通用格式），面向需要部署与管理 Cloudflare Workers 及相关平台资源的场景。官方描述其覆盖范围包括：Workers、KV、R2、D1、Vectorize、Hyperdrive、Workers AI、Containers、Queues、Workflows、Pipelines、Secrets Store 等。
该 Skill 有一个明确原则：Prefer retrieval over pre-training。也就是说，写或审查 Wrangler 命令、配置字段、绑定结构时，应优先从以下来源取最新信息，而不是依赖模型内置记忆：
| 来源 | 用途 |
|---|---|
https://developers.cloudflare.com/workers/wrangler/ |
CLI 命令、flag、配置参考 |
node_modules/wrangler/config-schema.json |
配置字段、binding 形状、允许值 |
https://developers.cloudflare.com/workers/ |
API、compatibility date/flag 等 |
它遵循 Agent Skills 开放标准，可在 Claude Code、Cursor、OpenCode、OpenAI Codex、Pi 等支持该标准的工具中使用。
核心功能与亮点¶
根据官方 SKILL.md，该 Skill 主要把助手引导到这些能力上：
- 安装与版本检查：先跑
wrangler --version（要求 v4.x+），未安装则用npm install -D wrangler@latest；能用 Wrangler 就不要手写 Cloudflare API 请求。 - 配置约定：优先使用
wrangler.jsonc（新功能多为 JSON 专用）；设置较近的compatibility_date；配置变更后执行wrangler types生成 TypeScript 绑定类型。 - 本地开发：默认本地存储模拟；需要连真实资源时在 binding 上设
remote: true；本地密钥放.dev.vars。 - 部署与运维：
deploy/--dry-run、密钥管理、版本列表与回滚、wrangler tail看实时日志、wrangler check startup分析启动耗时。 - 多资源生命周期：KV、R2、D1、Vectorize、Hyperdrive、Queues、Containers、Workflows、Pipelines、Secrets Store、Pages 等，均有对应子命令与配置 binding 示例。
- 安全习惯：密钥不要作为命令行参数或
echo管道传入；优先交互式wrangler secret put，或从文件 /secret bulk读取。
安装与启用¶
Skill 本身是指示文件；真正执行命令仍依赖本机已安装的 Wrangler（Node.js 项目中一般为 devDependency）。
1. 安装 Cloudflare Skills（含 wrangler）¶
官方 README 给出多种方式，任选其一即可。
用 npx skills 安装整个仓库（也可按 skills.sh 文档指定 --skill wrangler）：
npx skills add https://github.com/cloudflare/skills
# 仅安装 wrangler 时：
# npx skills add https://github.com/cloudflare/skills --skill wrangler
Claude Code（插件市场）：
/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare
Cursor：可从 Cursor Marketplace 安装，或在 Settings > Rules > Add Rule > Remote Rule (Github) 中添加 cloudflare/skills。
手动拷贝（官方目录对照）：
| 工具 | Skill 目录 |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Cursor | ~/.cursor/skills/ |
| OpenCode | ~/.config/opencode/skills/ |
| OpenAI Codex | ~/.codex/skills/ |
| Pi | ~/.pi/agent/skills/ |
例如：
git clone https://github.com/cloudflare/skills.git
cp -r skills/skills/wrangler ~/.cursor/skills/
安装后，当你让助手「部署 Worker」「改 wrangler.jsonc」「创建 D1」等，匹配到触发条件时会自动加载该 Skill；也可在对话里明确要求使用 wrangler skill。
2. 确保 Wrangler CLI 可用¶
wrangler --version # 需要 v4.x+
# 未安装时：
npm install -D wrangler@latest
典型用法示例¶
下面示例均来自官方 Skill 文档，可直接在项目中复现。
新建 Worker¶
npx wrangler init my-worker
# 或使用框架脚手架
npx create-cloudflare@latest my-app
最小配置（wrangler.jsonc）¶
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2026-01-01"
}
更完整的配置可同时声明 vars、kv_namespaces、r2_buckets、d1_databases、ai、vectorize、hyperdrive、durable_objects、triggers.crons 以及 env.staging 等环境覆盖。配置改完后建议：
wrangler types
# CI 中检查类型是否过期：
wrangler types --check
本地开发与部署¶
wrangler dev
wrangler deploy --dry-run
wrangler deploy
wrangler deploy --env staging
本地密钥示例（.dev.vars，勿提交到版本库）：
API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev
生产密钥用交互方式设置：
wrangler secret put API_KEY
常用命令速查¶
| 任务 | 命令 |
|---|---|
| 本地开发 | wrangler dev |
| 部署 | wrangler deploy |
| 干跑校验 | wrangler deploy --dry-run |
| 生成类型 | wrangler types |
| 启动耗时分析 | wrangler check startup |
| 实时日志 | wrangler tail |
| 账号状态 | wrangler whoami |
D1 迁移、R2 对象上传、KV 读写等，Skill 中也有对应命令模板，例如：
wrangler d1 migrations create my-database create_users_table
wrangler d1 migrations apply my-database --local
wrangler d1 migrations apply my-database --remote
wrangler r2 bucket create my-bucket
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt
wrangler kv namespace create MY_KV
适用场景与注意事项¶
适合：
- 用 AI 助手写/改 Cloudflare Workers 项目配置与部署脚本
- 需要同时管理 KV、R2、D1、Queues 等多类绑定，希望命令与 schema 对齐
- 团队把
wrangler.jsonc当作配置单一事实来源，并在 CI 里跑wrangler types --check
注意：
- Skill 指导的是「怎么正确用 Wrangler」；账号登录（
wrangler login）、计费与配额仍以 Cloudflare 控制台与官方文档为准。 - Workers AI 在本地开发时也会走远端并产生用量，Skill 明确标出了这一点。
- 本地默认用模拟存储；需要连真实 R2 / Vectorize / AI 等时，在对应 binding 上配置
remote: true。 - 命令与配置字段会变；启用该 Skill 的意义之一，就是让助手在动手前去查文档和
config-schema.json，而不是背旧语法。 - 第三方镜像站上的安装命令若与官方 README / skills.sh 不一致，以 Cloudflare 仓库与 skills.sh 上的 wrangler 页 为准。
小结¶
Wrangler Skill 把 Cloudflare 官方对 CLI 与配置的最新约定，固化成 Agent 可加载的操作手册：先检索、再落命令，优先 wrangler.jsonc、类型生成、安全管密钥、本地先测再部署。对已经在用 Workers 边缘栈的开发者来说，把它装进 Cursor / Claude Code / Codex 等工具，能明显减少「过时 flag」和「错误 binding」这类问题。
官方地址：
- Skill 目录：https://github.com/cloudflare/skills/tree/main/skills/wrangler
- 仓库说明与安装：https://github.com/cloudflare/skills
- Wrangler 文档：https://developers.cloudflare.com/workers/wrangler/
- skills.sh 安装页：https://www.skills.sh/cloudflare/skills/wrangler
