wrangler

使用 Wrangler

版本： 4.59.2+（2026 年 1 月）。配置格式：推荐使用 wrangler.jsonc，而不是 .toml。

快速入门

# Create new project
npx create-cloudflare@latest my-worker

# Local dev
wrangler dev

# Deploy
wrangler deploy

# View logs
wrangler tail

精确提示词 — 部署 Worker

Deploy Worker to Cloudflare:
1. Check wrangler.jsonc exists with name, main, compatibility_date
2. wrangler deploy (auto-provisions KV/R2/D1 bindings if IDs missing)
3. wrangler tail to verify

核心命令

任务	命令
本地开发	wrangler dev
部署	wrangler deploy
查看日志	wrangler tail
添加密钥	wrangler secret put NAME
列出密钥	wrangler secret list
生成类型	wrangler types
检查配置	wrangler check startup

配置（wrangler.jsonc）

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",

  // Routes
  "routes": [
    { "pattern": "example.com/*", "zone_name": "example.com" }
  ],

  // Bindings (IDs optional - auto-provisioned on deploy)
  "kv_namespaces": [{ "binding": "KV", "id": "..." }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
  "d1_databases": [{ "binding": "DB", "database_id": "..." }],

  // Environment variables
  "vars": { "ENV": "production" }
}

自动预配（v4.57+）

添加绑定时无需提供 ID — Wrangler 会在部署时创建资源：

{
  "kv_namespaces": [{ "binding": "CACHE" }],  // No id - auto-created
  "r2_buckets": [{ "binding": "ASSETS" }],    // No bucket_name - auto-created
  "d1_databases": [{ "binding": "DB" }]       // No database_id - auto-created
}

隐藏／实验性标志

标志	用途
--x-provision	强制自动预配资源
--x-auto-create	使用新资源自动创建绑定
--x-autoconfig	自动检测框架（Next.js、Remix 等）

环境变量

变量	用途
CLOUDFLARE_API_TOKEN	用于 CI/CD 的身份验证
CLOUDFLARE_ACCOUNT_ID	覆盖账户

决策树

What to do?
├─ New project → npx create-cloudflare@latest
├─ Local dev → wrangler dev
├─ Deploy → wrangler deploy
├─ Add secret → wrangler secret put NAME
├─ View logs → wrangler tail
├─ Database ops → wrangler d1 ...
├─ Storage ops → wrangler r2 ... or wrangler kv ...
└─ Scheduled jobs → Add [triggers] to config

常见模式

添加密钥

wrangler secret put API_KEY
# Enter value when prompted (or pipe: echo "value" | wrangler secret put API_KEY)

多个环境

{
  "name": "my-worker",
  "env": {
    "staging": {
      "vars": { "ENV": "staging" },
      "routes": [{ "pattern": "staging.example.com/*" }]
    },
    "production": {
      "vars": { "ENV": "production" },
      "routes": [{ "pattern": "example.com/*" }]
    }
  }
}

wrangler deploy --env staging
wrangler deploy --env production

D1 数据库

wrangler d1 create my-db
wrangler d1 execute my-db --file schema.sql
wrangler d1 execute my-db --command "SELECT * FROM users"

R2 存储

wrangler r2 bucket create my-bucket
wrangler r2 object put my-bucket/file.txt --file ./local.txt
wrangler r2 object get my-bucket/file.txt

---

AGENTS.md 说明

将此内容复制到项目的 AGENTS.md：

### Cloudflare Wrangler

Wrangler is installed and authenticated.

R2 bucket: `<BUCKET_NAME>`
Account ID: `<ACCOUNT_ID>`

Common commands:

\`\`\`bash
wrangler r2 object put <BUCKET>/<path> --file ./local-file
wrangler r2 object get <BUCKET>/<path> --file ./downloaded
wrangler r2 bucket list
wrangler d1 execute <DB> --command "SELECT * FROM users"
wrangler deploy
\`\`\`

---

参考索引

主题	参考资料
所有命令	COMMANDS.md
配置选项	CONFIG.md
Pages 部署	PAGES.md

注意事项

• 控制面板中的更改会被覆盖： 添加 "keep_vars": true 以保留控制面板中的编辑
• 配置中不能包含密钥： 使用 wrangler secret put，切勿将密钥放入配置中
• 类型已过时： 配置更改后运行 wrangler types
• compatibility_date 过旧： 每年更新，以使用新功能

来源

• 仓库：cloudflare/workers-sdk @ v4.59.2
• 文档：developers.cloudflare.com/workers/wrangler