name: cloudflare
description: 使用 Wrangler CLI 管理 Cloudflare Workers、KV、D1、R2 和密钥。适用于部署 Worker、管理数据库、存储对象或配置 Cloudflare 资源。涵盖 Worker 部署、KV 命名空间、D1 SQL 数据库、R2 对象存储、密钥管理和日志追踪。

Cloudflare (Wrangler CLI)

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

先决条件

• 需要 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]

密钥

# 添加/更新密钥（交互式）
wrangler secret put <key>

# 从标准输入添加密钥
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>

队列

# 创建队列
wrangler queues create <name>

# 列出队列
wrangler queues list

# 删除队列
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 绑定
[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"

# D1 绑定
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxx"

# R2 绑定
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

# 环境变量
[vars]
API_URL = "https://api.example.com"

# 密钥（通过 `wrangler secret put` 设置）
# 在 Worker 代码中通过 env.SECRET_NAME 引用

静态资源（适用于 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 不直接管理自定义域名。

本地开发与绑定

# 为开发环境创建本地 D1/KV/R2 实例
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 文档