⌨️ Wrangler CLI

Wrangler 是 Cloudflare 官方命令行工具，用于开发、测试和部署 Workers、Pages 及其他 Cloudflare 服务。

安装 Wrangler

全局安装（推荐）

npm install -g wrangler

项目本地安装

npm install --save-dev wrangler

验证安装

wrangler --version
# 输出：⛅️ wrangler 4.46.0

认证登录

# 登录 Cloudflare 账户
wrangler login

# 登出
wrangler logout

# 查看当前用户信息
wrangler whoami

核心命令概览

项目初始化

wrangler init [name]

本地开发

wrangler dev [script]

部署

wrangler deploy [script]

查看日志

wrangler tail [worker]

Workers 命令

创建和初始化

# 创建新 Worker 项目
wrangler init my-worker

# 使用交互式向导
npm create cloudflare@latest

开发和调试

# 启动本地开发服务器
wrangler dev

# 指定端口
wrangler dev --port 3000

# 启用远程模式（使用真实的 Cloudflare 网络）
wrangler dev --remote

# 指定环境
wrangler dev --env production

部署

# 部署到生产环境
wrangler deploy

# 部署特定文件
wrangler deploy src/index.js

# 部署到指定环境
wrangler deploy --env staging

# 显示部署详情
wrangler deploy --dry-run

版本管理

# 上传新版本（不部署）
wrangler versions upload

# 查看所有版本
wrangler versions list

# 查看版本详情
wrangler versions view {version-id}

# 部署特定版本
wrangler versions deploy --version-id {version-id}

# 回滚到上一个版本
wrangler rollback

查看和管理

# 查看部署历史
wrangler deployments list

# 查看实时日志
wrangler tail

# 筛选日志
wrangler tail --status ok
wrangler tail --status error

# 删除 Worker
wrangler delete my-worker

Pages 命令

Wrangler Pages 命令
# 部署到 Pages
wrangler pages deploy {directory}

# 指定项目名称
wrangler pages deploy dist --project-name=my-site

# 指定分支
wrangler pages deploy dist --branch=main

# 创建新 Pages 项目
wrangler pages project create my-project

# 列出所有 Pages 项目
wrangler pages project list

# 查看项目详情
wrangler pages project get my-project

# 删除 Pages 项目
wrangler pages project delete my-project

# 查看部署历史
wrangler pages deployment list

# 本地开发（模拟 Pages 环境）
wrangler pages dev dist

# 使用 Functions
wrangler pages dev dist --port 8788

D1 数据库命令

Wrangler D1 命令
# 创建数据库
wrangler d1 create my-database

# 列出所有数据库
wrangler d1 list

# 执行 SQL 命令
wrangler d1 execute my-database --command="SELECT * FROM users"

# 执行 SQL 文件
wrangler d1 execute my-database --file=schema.sql

# 本地开发模式
wrangler d1 execute my-database --local --command="SELECT * FROM users"

# 导出数据
wrangler d1 export my-database --output=backup.sql

# 删除数据库
wrangler d1 delete my-database

# Time Travel 恢复
wrangler d1 time-travel restore my-database --timestamp=2024-01-01T12:00:00Z

KV 命令

Wrangler KV 命令
# 创建 KV 命名空间
wrangler kv namespace create MY_KV

# 创建预览命名空间
wrangler kv namespace create MY_KV --preview

# 列出所有命名空间
wrangler kv namespace list

# 写入键值
wrangler kv key put --binding=MY_KV "mykey" "myvalue"

# 读取键值
wrangler kv key get --binding=MY_KV "mykey"

# 列出所有键
wrangler kv key list --binding=MY_KV

# 删除键
wrangler kv key delete --binding=MY_KV "mykey"

# 批量导入
wrangler kv bulk put --binding=MY_KV data.json

# 批量删除
wrangler kv bulk delete --binding=MY_KV keys.json

R2 命令

Wrangler R2 命令
# 创建 R2 存储桶
wrangler r2 bucket create my-bucket

# 列出所有存储桶
wrangler r2 bucket list

# 查看存储桶详情
wrangler r2 bucket get my-bucket

# 删除存储桶
wrangler r2 bucket delete my-bucket

# 上传对象
wrangler r2 object put my-bucket/file.txt --file=./local-file.txt

# 下载对象
wrangler r2 object get my-bucket/file.txt --file=./downloaded-file.txt

# 列出对象
wrangler r2 object list my-bucket

# 删除对象
wrangler r2 object delete my-bucket/file.txt

Secret 管理

# 添加 Secret
wrangler secret put API_KEY

# 列出所有 Secret（只显示名称）
wrangler secret list

# 删除 Secret
wrangler secret delete API_KEY

# 批量添加 Secret
wrangler secret bulk < secrets.json

其他服务命令

Queues（队列）

# 创建队列
wrangler queues create my-queue

# 列出队列
wrangler queues list

# 发送消息
wrangler queues producer my-queue send "Hello Queue"

# 删除队列
wrangler queues delete my-queue

Vectorize（向量数据库）

# 创建 Vectorize 索引
wrangler vectorize create my-index --dimensions=768

# 列出索引
wrangler vectorize list

# 查看索引详情
wrangler vectorize get my-index

# 删除索引
wrangler vectorize delete my-index

Hyperdrive（数据库加速）

# 创建 Hyperdrive 配置
wrangler hyperdrive create my-config --connection-string="postgres://..."

# 列出配置
wrangler hyperdrive list

# 查看配置
wrangler hyperdrive get my-config

# 更新配置
wrangler hyperdrive update my-config --connection-string="postgres://..."

# 删除配置
wrangler hyperdrive delete my-config

类型生成

# 生成 TypeScript 类型定义
wrangler types

# 指定输出路径
wrangler types --output=src/types.d.ts

配置文件

wrangler.toml

wrangler.toml 完整示例
name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

# 账户信息
account_id = "your-account-id"

# 路由配置
routes = [
  { pattern = "example.com/*", zone_name = "example.com" }
]

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

# KV 绑定
[[kv_namespaces]]
binding = "MY_KV"
id = "your-kv-id"

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

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

# Vectorize 绑定
[[vectorize]]
binding = "VECTORIZE"
index_name = "my-index"

# Cron 触发器
[triggers]
crons = ["0 0 * * *"]

# 兼容性标志
[compatibility_flags]
nodejs_compat = true

# 环境配置
[env.production]
vars = { ENVIRONMENT = "production" }

[env.staging]
vars = { ENVIRONMENT = "staging" }

wrangler.jsonc（新推荐格式）

wrangler.jsonc 示例
{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",
  "vars": {
    "API_ENDPOINT": "https://api.example.com"
  },
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "your-kv-id"
    }
  ],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "your-db-id"
    }
  ]
}

实用技巧

1. 使用环境变量

# 创建 .dev.vars 文件（本地开发）
API_KEY=your-local-api-key
DATABASE_URL=http://localhost:5432

# 生产环境使用 wrangler secret

2. 调试技巧

# 启用详细日志
wrangler dev --log-level debug

# 查看构建输出
wrangler deploy --outdir=dist

# 使用 console.log 调试
wrangler tail --format=pretty

3. 多环境管理

# 本地开发
wrangler dev --env development

# 预发布环境
wrangler deploy --env staging

# 生产环境
wrangler deploy --env production

常见问题

Q: 如何查看帮助？

wrangler --help

Q: 如何查看特定命令的帮助？

wrangler deploy --help

Q: 如何更新 Wrangler？

npm install -g wrangler@latest

Q: 如何在 CI/CD 中使用？

# 设置环境变量
export CLOUDFLARE_API_TOKEN="your-api-token"

# 部署
wrangler deploy

全局参数

# 指定配置文件
wrangler deploy --config wrangler.custom.toml

# 指定工作目录
wrangler deploy --cwd /path/to/project

# 指定环境
wrangler deploy --env production

# 指定环境变量文件
wrangler dev --env-file .env.local

相关资源