前言¶
在 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
