Cloudflare CLI (Wrangler) 速查手册

10分钟快速掌握 Cloudflare CLI 核心功能

🌟 什么是 Cloudflare CLI？

Cloudflare CLI (官方名称: Wrangler) 是 Cloudflare 官方提供的命令行工具，让开发者能够通过终端管理 Cloudflare 的各种服务。

🎯 主要用途

部署和管理 Cloudflare Workers (无服务器函数)
发布和托管 静态网站到 Cloudflare Pages
操作数据库 Cloudflare D1 (SQLite 兼容)
管理文件存储 Cloudflare R2 (S3 兼容)
配置 CDN 和边缘计算服务

🚀 为什么要用？

🌍 全球边缘网络: 你的应用部署到全球 200+ 数据中心
⚡ 零冷启动: Workers 响应时间 < 1ms
💰 成本友好: 慷慨的免费额度，按需付费
🔧 开发友好: 本地开发 + 一键部署
🛡️ 内置安全: DDoS 防护、SSL/TLS 自动配置

🏗️ 适用场景

API 开发: 构建高性能 RESTful API
静态网站: React、Vue、Next.js 等框架部署
微服务: 拆分单体应用为边缘函数
图片处理: 实时图片优化和转换
代理服务: 请求转发、负载均衡

⚡ 5分钟快速体验

# 1. 安装 Wrangler
npm install -g wrangler

# 2. 登录账户 (会打开浏览器授权)
wrangler auth login

# 3. 创建第一个 Worker
wrangler generate my-first-worker

# 4. 进入项目目录
cd my-first-worker

# 5. 本地预览 (访问 http://localhost:8787)
wrangler dev

# 6. 部署到生产环境
wrangler deploy

# 发布静态网站
wrangler pages deploy <directory>

# 发布到指定项目
wrangler pages deploy <directory> --project-name=<project-name>

# 查看 Pages 项目列表
wrangler pages project list

# 删除 Pages 项目
wrangler pages project delete <project-name>

# 查看部署历史
wrangler pages deployment list --project-name=<project-name>

⚡ Cloudflare Workers

# 创建新的 Worker 项目
wrangler generate <project-name>

# 本地开发服务器
wrangler dev

# 发布 Worker
wrangler deploy

# 查看 Worker 列表
wrangler list

# 删除 Worker
wrangler delete <worker-name>

# 查看 Worker 日志
wrangler tail <worker-name>

# 发布到指定环境
wrangler deploy --env production

🗄️ Cloudflare D1 数据库

# 创建 D1 数据库
wrangler d1 create <database-name>

# 查看数据库列表
wrangler d1 list

# 执行 SQL 查询
wrangler d1 execute <database-name> --command="SELECT * FROM users"

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

# 本地开发数据库
wrangler d1 execute <database-name> --local --command="SELECT * FROM users"

# 删除数据库
wrangler d1 delete <database-name>

📁 Cloudflare R2 对象存储

# 创建 R2 存储桶
wrangler r2 bucket create <bucket-name>

# 查看存储桶列表
wrangler r2 bucket list

# 上传文件
wrangler r2 object put <bucket-name>/<object-key> --file=<local-file>

# 下载文件
wrangler r2 object get <bucket-name>/<object-key> --file=<local-file>

# 列出对象
wrangler r2 object list <bucket-name>

# 删除对象
wrangler r2 object delete <bucket-name>/<object-key>

# 删除存储桶
wrangler r2 bucket delete <bucket-name>

🔧 配置文件 (wrangler.toml)

# 基本配置
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

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

# 环境配置
[env.production]
vars = { API_URL = "https://prod-api.example.com" }

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

# R2 存储桶绑定
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

# KV 命名空间绑定
[[kv_namespaces]]
binding = "MY_KV"
id = "your-kv-id"

🎯 常用快捷命令

# 快速初始化项目
wrangler init <project-name>

# 生成类型定义
wrangler types

# 查看密钥
wrangler secret list

# 设置密钥
wrangler secret put <key-name>

# 删除密钥
wrangler secret delete <key-name>

# 查看使用情况
wrangler analytics

# 更新 Wrangler
npm update -g wrangler

💡 实用技巧

1. 环境变量管理最佳实践

🚨 重要提醒: 目前 Wrangler 不支持自动读取 .env 文件进行部署。预计 2025.08 后可能会支持标准 .env 文件，但现阶段请使用以下推荐方式：

方式一: .dev.vars + wrangler secret (推荐)

# 本地开发环境变量 (不提交到 Git)
echo "API_KEY=your-dev-key" > .dev.vars
echo "DATABASE_URL=local-db-url" >> .dev.vars

# 本地开发
wrangler dev  # ✅ 自动读取 .dev.vars 文件

# 生产环境使用 secret 管理敏感信息
wrangler secret put API_KEY --env production
wrangler secret put DATABASE_URL --env production
wrangler secret put API_KEY --env staging

# 部署
wrangler deploy --env production
wrangler deploy --env staging

方式二: wrangler.toml 配置文件管理

# 创建配置模板 (可提交到 Git)
cp wrangler.toml wrangler.example.toml

# 在 wrangler.toml 中配置不同环境 (不提交到 Git)

wrangler.toml 示例配置:

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# 开发环境 (默认)
[vars]
API_URL = "https://dev-api.example.com"
ENVIRONMENT = "development"

# 测试环境
[env.staging]
vars = { 
  API_URL = "https://staging-api.example.com",
  ENVIRONMENT = "staging"
}

# 生产环境
[env.production]
vars = { 
  API_URL = "https://api.example.com",
  ENVIRONMENT = "production"
}

📁 文件管理规范:

.dev.vars - 本地开发环境变量 (不提交)
wrangler.toml - 项目配置文件 (包含敏感信息时不提交)
wrangler.example.toml - 配置模板 (可提交)

🔍 环境说明:

development = 本地开发环境
staging = 测试/预发布环境
production = 生产环境

🔒 .gitignore 配置:

# 本地开发环境变量 (敏感信息，不提交)
.dev.vars

# 包含敏感信息的配置文件 (不提交)
wrangler.toml

# 保留模板文件 (可提交)
!wrangler.example.toml

📝 wrangler.example.toml 模板示例:

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# 开发环境 (默认) - 本地运行时使用
[vars]
API_URL = "https://dev-api.example.com"
ENVIRONMENT = "development"
# API_KEY = "your-api-key"  # 使用 .dev.vars 或 wrangler secret

# 测试环境
[env.staging]
vars = { 
  API_URL = "https://staging-api.example.com",
  ENVIRONMENT = "staging"
}
# 敏感变量使用: wrangler secret put API_KEY --env staging

# 生产环境
[env.production]
vars = { 
  API_URL = "https://api.example.com",
  ENVIRONMENT = "production"
}
# 敏感变量使用: wrangler secret put API_KEY --env production

🔍 环境变量读取优先级说明:

本地开发 (wrangler dev):
- 首先读取 .dev.vars 文件（如果存在）
- 然后读取 wrangler.toml 中的 [vars] 部分（默认环境）
- 如果只有 [env.production] 而没有 [vars]，本地开发将无法读取到这些变量
生产部署 (wrangler deploy --env production):
- 读取 wrangler.toml 中的 [env.production.vars] 部分
- 加载通过 wrangler secret put 设置的密钥

重要提醒:

# ❌ 错误：如果只有 env.production，本地开发无变量
wrangler dev  # 无法读取 env.production 的变量

# ✅ 正确：需要添加默认 [vars] 或使用 .dev.vars
wrangler dev  # 读取 [vars] + .dev.vars

2. 本地开发最佳实践

# 使用 .dev.vars 文件 (Wrangler 自动读取)
wrangler dev

# 手动指定环境变量文件
wrangler dev --var API_KEY=test-key

# 指定端口启动开发服务器
wrangler dev --port 3000

# 启用兼容模式
wrangler dev --compatibility-date=2024-01-01

3. 多环境管理

# 部署到测试环境
wrangler deploy --env staging

# 部署到生产环境
wrangler deploy --env production

# 查看特定环境的日志
wrangler tail my-worker --env production

4. 调试技巧

# 查看详细日志
wrangler tail <worker-name> --format=pretty

# 过滤日志
wrangler tail <worker-name> --status=error

# 实时查看异常
wrangler tail <worker-name> --debug

5. 优化开发体验

# 避免每次都要确认发送使用数据
# 在 .env 文件中设置（如果项目支持）
echo "WRANGLER_SEND_METRICS=false" >> .env

# 或者在系统环境变量中设置
export WRANGLER_SEND_METRICS=false

# 也可以在 .bashrc 或 .zshrc 中永久设置
echo "export WRANGLER_SEND_METRICS=false" >> ~/.zshrc
source ~/.zshrc

📝 说明:

WRANGLER_SEND_METRICS=false 会禁用 Wrangler 的使用数据收集
避免每次执行命令时都要输入 y/n 确认
提升开发效率，特别是在 CI/CD 环境中

📚 资源链接

🆘 常见问题

登录问题

# 重新登录
wrangler auth logout
wrangler auth login

# 使用 API Token
wrangler auth login --scoped-key

部署失败

# 检查配置文件
wrangler validate

# 查看详细错误信息
wrangler deploy --verbose

💡 小贴士: 大部分命令都支持 --help 参数查看详细说明，如 wrangler deploy --help

Cloudflare CLI (Wrangler) 速查手册

On this page