用途
该技能用于通过 Wrangler CLI 管理 Cloudflare Workers 及其关联服务，包括 KV、D1、R2、Queues 和 Secrets。适合在部署 Worker、管理数据库、存储对象或配置绑定时使用。
前置条件
- 需要 Node.js v20+。
- 安装：
npm install -g wrangler，或使用项目本地的npx wrangler。 - 认证：
wrangler login（打开浏览器进行 OAuth）。 - 验证：
wrangler whoami。
主要能力
Workers
- 初始化新 Worker：
wrangler init <name> - 本地开发：
wrangler dev [script] - 部署：
wrangler deploy [script] - 列出部署：
wrangler deployments list - 查看部署：
wrangler deployments view [deployment-id] - 回滚：
wrangler rollback [version-id] - 删除 Worker：
wrangler delete [name] - 实时日志：
wrangler tail [worker]
Secrets
- 交互式添加/更新密钥：
wrangler secret put <key> - 从 stdin 添加：
echo "value" | wrangler secret put <key> - 列出密钥：
wrangler secret list - 删除密钥：
wrangler secret delete <key> - 从 JSON 文件批量上传：
wrangler secret bulk secrets.json
KV（键值存储）
- 创建命名空间：
wrangler kv namespace create <name> - 列出命名空间：
wrangler kv namespace list - 删除命名空间：
wrangler kv namespace delete --namespace-id <id> - 写入键：
wrangler kv key put <key> <value> --namespace-id <id> - 读取键：
wrangler kv key get <key> --namespace-id <id> - 删除键：
wrangler kv key delete <key> --namespace-id <id> - 列出键：
wrangler kv key list --namespace-id <id> - 批量操作（JSON 文件）：
wrangler kv bulk put <file> --namespace-id <id>、wrangler kv bulk delete <file> --namespace-id <id>
D1（SQL 数据库）
- 创建数据库：
wrangler d1 create <name> - 列出数据库：
wrangler d1 list - 数据库信息：
wrangler d1 info <name> - 执行 SQL：
wrangler d1 execute <database> --command "SELECT * FROM users" - 执行 SQL 文件：
wrangler d1 execute <database> --file schema.sql - 本地执行（开发用）：
wrangler d1 execute <database> --local --command "..." - 导出数据库：
wrangler d1 export <name> --output backup.sql - 删除数据库：
wrangler d1 delete <name> - 迁移：
wrangler d1 migrations create <database> <name>、wrangler d1 migrations apply <database>、wrangler d1 migrations list <database>
R2（对象存储）
- 创建存储桶：
wrangler r2 bucket create <name> - 列出存储桶：
wrangler r2 bucket list - 删除存储桶：
wrangler r2 bucket delete <name> - 上传对象：
wrangler r2 object put <bucket>/<key> --file <path> - 下载对象：
wrangler r2 object get <bucket>/<key> --file <path> - 删除对象：
wrangler r2 object delete <bucket>/<key>
Queues
- 创建队列：
wrangler queues create <name> - 列出队列：
wrangler queues list - 删除队列：
wrangler queues delete <name>
配置文件
Wrangler 支持 TOML 和 JSON/JSONC 两种配置格式：
wrangler.toml— 传统格式wrangler.json或wrangler.jsonc— 较新格式，支持 JSON schema
重要：如果两者同时存在，JSON 优先。建议只选一种格式，避免 TOML 的修改被忽略。
JSONC 格式（带 schema 自动补全）：
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2024-12-30"
}
TOML 格式：
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"
带绑定的 TOML 示例：
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"
# KV binding
[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"
# D1 binding
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxx"
# R2 binding
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"
# Environment variables
[vars]
API_URL = "https://api.example.com"
# Secrets (set via `wrangler secret put`)
# Referenced as env.SECRET_NAME in worker code
静态资源（用于 Next.js 等框架）：
name = "my-site"
main = ".open-next/worker.js"
compatibility_date = "2024-12-30"
compatibility_flags = ["nodejs_compat"]
[assets]
directory = ".open-next/assets"
binding = "ASSETS"
常见模式
- 按环境部署：
wrangler deploy -e production、wrangler deploy -e staging - 自定义域名：必须在 Cloudflare 仪表盘的 Worker Settings > Domains & Routes 中配置，或通过 Cloudflare API 配置。Wrangler 不直接管理自定义域名。
- 带绑定的本地开发：
wrangler dev --local（为开发创建本地 D1/KV/R2） - 检查部署状态：
wrangler deployments list、wrangler deployments view
Wrangler 不负责的内容
- DNS 管理 — 使用 Cloudflare 仪表盘或 API 管理 DNS 记录
- 自定义域名 — 通过仪表盘（Worker Settings > Domains & Routes）或 API 配置
- SSL 证书 — 添加自定义域名时由 Cloudflare 自动管理
- 防火墙/WAF 规则 — 使用仪表盘或 API
如需 DNS/域名管理，请参考 cloudflare 技能（直接使用 Cloudflare API）。
故障排查
| 问题 | 解决方案 |
|---|---|
| "Not authenticated" | 运行 wrangler login |
| Node 版本错误 | 需要 Node.js v20+ |
| "No config found" | 确保配置文件存在（wrangler.toml 或 wrangler.jsonc），或使用 -c path/to/config |
| 配置修改被忽略 | 检查是否存在 wrangler.json/wrangler.jsonc — JSON 优先于 TOML |
| 找不到绑定 | 检查 wrangler.toml 中的绑定是否与代码引用一致 |
适用场景
- 部署和管理 Cloudflare Workers
- 管理 KV 键值存储、D1 SQL 数据库、R2 对象存储和 Queues 队列
- 配置和管理 Secrets 密钥
- 本地开发与调试 Worker 及其绑定资源
限制
- 需要 Node.js v20+ 环境。
- 不负责 DNS 管理、自定义域名、SSL 证书和防火墙/WAF 规则，这些需通过 Cloudflare 仪表盘或 API 处理。
- 自定义域名无法通过 Wrangler 直接管理。
- 同时存在 TOML 和 JSON 配置时，JSON 优先，可能导致 TOML 修改被忽略。