Cloudflare (Wrangler CLI)

通过wranglerCLI 管理 Cloudflare Workers 及相关服务。

前提条件

• 需要 Node.js v20 或更高版本
• 安装：npm install -g wrangler或使用项目本地安装npx wrangler
• 认证：wrangler login（通过浏览器进行 OAuth 认证）
• 验证：wrangler whoami

快速参考

Workers

# Initialize new worker
wrangler init <name>

# Local development
wrangler dev [script]

# Deploy
wrangler deploy [script]

# List deployments
wrangler deployments list

# View deployment
wrangler deployments view [deployment-id]

# Rollback
wrangler rollback [version-id]

# Delete worker
wrangler delete [name]

# Tail logs (live)
wrangler tail [worker]

Secrets

# Add/update secret (interactive)
wrangler secret put <key>

# Add secret from stdin
echo "value" | wrangler secret put <key>

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete <key>

# Bulk upload from JSON file
wrangler secret bulk secrets.json

KV（键值存储）

# Create namespace
wrangler kv namespace create <name>

# List namespaces
wrangler kv namespace list

# Delete namespace
wrangler kv namespace delete --namespace-id <id>

# Put key
wrangler kv key put <key> <value> --namespace-id <id>

# Get key
wrangler kv key get <key> --namespace-id <id>

# Delete key
wrangler kv key delete <key> --namespace-id <id>

# List keys
wrangler kv key list --namespace-id <id>

# Bulk operations (JSON file)
wrangler kv bulk put <file> --namespace-id <id>
wrangler kv bulk delete <file> --namespace-id <id>

D1（SQL 数据库）

# Create database
wrangler d1 create <name>

# List databases
wrangler d1 list

# Database info
wrangler d1 info <name>

# Execute SQL
wrangler d1 execute <database> --command "SELECT * FROM users"

# Execute SQL file
wrangler d1 execute <database> --file schema.sql

# Local execution (for dev)
wrangler d1 execute <database> --local --command "..."

# Export database
wrangler d1 export <name> --output backup.sql

# Delete database
wrangler d1 delete <name>

# Migrations
wrangler d1 migrations create <database> <name>
wrangler d1 migrations apply <database>
wrangler d1 migrations list <database>

R2（对象存储）

# Create bucket
wrangler r2 bucket create <name>

# List buckets
wrangler r2 bucket list

# Delete bucket
wrangler r2 bucket delete <name>

# Upload object
wrangler r2 object put <bucket>/<key> --file <path>

# Download object
wrangler r2 object get <bucket>/<key> --file <path>

# Delete object
wrangler r2 object delete <bucket>/<key>

Queues

# Create queue
wrangler queues create <name>

# List queues
wrangler queues list

# Delete queue
wrangler queues delete <name>

配置文件

Wrangler 支持 TOML 和 JSON/JSONC 配置格式：

• wrangler.toml— 传统格式
• wrangler.json或wrangler.jsonc— 更新的格式，支持 JSON 模式

⚠️ 重要提示：如果两种格式同时存在，JSON 格式优先。请选择一种格式以避免对 TOML 的修改被忽略而造成混淆。

JSONC 格式（支持模式自动补全）

{
  "$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"

包含绑定：

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

自定义域名（通过控制面板或 API）

自定义域名必须在 Cloudflare 控制面板的 Worker 设置 > 域名和路由中配置，或通过 Cloudflare API 配置。Wrangler 不直接管理自定义域名。

使用绑定的本地开发

# Creates local D1/KV/R2 for dev
wrangler dev --local

检查部署状态

wrangler deployments list
wrangler deployments view

Wrangler 不执行的操作

• DNS 管理— 通过Cloudflare仪表板或API管理DNS记录
• 自定义域名— 通过仪表板（Worker设置 > 域名与路由）或API配置
• SSL证书— 添加自定义域名时由Cloudflare自动管理
• 防火墙/WAF规则— 使用仪表板或API

关于DNS/域名管理，请参阅cloudflare技能（直接使用Cloudflare API）。

故障排除

资源

• Wrangler 文档
• Workers 文档
• D1 文档
• R2 文档
• KV 文档