Wrangler 是 Cloudflare Workers 的官方命令行工具，用于开发、测试和部署 Serverless 应用。本文档涵盖常用命令和最佳实践。
目录
- 安装与配置
- D1 数据库管理
- R2 对象存储
- 环境变量与密钥
- 开发与部署
- 定时任务 (Cron Triggers)
- 日志与监控
- 最佳实践
安装与配置
使用 npx（推荐）
无需全局安装，直接使用 npx 调用：
npx wrangler <command>
优势：
- 始终使用项目依赖中的 wrangler 版本
- 避免全局版本冲突
- 团队协作时版本一致
全局安装
npm install -g wrangler
登录认证
npx wrangler login
执行后会打开浏览器，完成 Cloudflare 账户授权。
D1 数据库管理
D1 是 Cloudflare 提供的 Serverless SQLite 数据库。
创建数据库
npx wrangler d1 create <database-name>
输出示例：
✅ Successfully created DB 'my-database'
binding = "DB"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
将输出的配置添加到 wrangler.jsonc：
{"d1_databases": [{"binding": "DB","database_name": "my-database","database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}]
}
执行 SQL 文件
本地环境：
npx wrangler d1 execute <database-name> --local --file=schema.sql
远程环境（生产）：
npx wrangler d1 execute <database-name> --remote --file=schema.sql
执行 SQL 命令
npx wrangler d1 execute <database-name> --remote --command="SELECT * FROM users LIMIT 10;"
执行多条语句：
npx wrangler d1 execute <database-name> --remote --command="INSERT INTO users (id, name) VALUES ('1', 'Alice');INSERT INTO users (id, name) VALUES ('2', 'Bob');
"
导出数据库
npx wrangler d1 export <database-name> --remote --output=backup.sql
用途：
- 数据备份
- 迁移数据到其他环境
- 审查数据库结构
查看数据库列表
npx wrangler d1 list
删除数据库
npx wrangler d1 delete <database-name>
注意： 此操作不可逆，请谨慎使用。
R2 对象存储
R2 是 Cloudflare 的对象存储服务，兼容 S3 API。
创建存储桶
npx wrangler r2 bucket create <bucket-name>
配置到 wrangler.jsonc：
{"r2_buckets": [{"binding": "BUCKET","bucket_name": "my-bucket"}]
}
列出所有存储桶
npx wrangler r2 bucket list
查看存储桶信息
npx wrangler r2 bucket info <bucket-name>
列出存储桶中的对象
npx wrangler r2 object list <bucket-name>
分页查询：
npx wrangler r2 object list <bucket-name> --limit=100
上传对象
npx wrangler r2 object put <bucket-name>/path/to/file.jpg --file=./local/file.jpg
下载对象
npx wrangler r2 object get <bucket-name>/path/to/file.jpg --file=./downloaded.jpg
删除对象
npx wrangler r2 object delete <bucket-name>/path/to/file.jpg
删除存储桶
npx wrangler r2 bucket delete <bucket-name>
注意： 存储桶必须为空才能删除。
环境变量与密钥
Secret（加密密钥）
设置 Secret：
npx wrangler secret put API_KEY
执行后会提示输入密钥值：
Enter a secret value: ****************
列出所有 Secrets：
npx wrangler secret list
删除 Secret：
npx wrangler secret delete API_KEY
本地开发环境变量
创建 .dev.vars 文件（不要提交到 Git）：
API_KEY=your-api-key-here
DATABASE_URL=sqlite://local.db
DEBUG=true
在 .gitignore 中排除：
.dev.vars
在代码中访问
export default {async fetch(request: Request, env: Env) {const apiKey = env.API_KEY; // 读取 Secret 或环境变量// ...}
}
开发与部署
本地开发
npx wrangler dev
指定端口：
npx wrangler dev --port=3000
启用远程模式（使用生产 D1/R2）：
npx wrangler dev --remote
部署到生产环境
npx wrangler deploy
部署特定入口文件：
npx wrangler deploy src/index.ts
查看部署历史
npx wrangler deployments list
输出示例：
Deployment ID: xxxxxx
Created: 2025-12-28 10:30:00
Author: user@example.com
回滚到上一个版本
npx wrangler rollback
回滚到特定版本：
npx wrangler rollback --deployment-id=xxxxxx
定时任务 (Cron Triggers)
配置 Cron 触发器
在 wrangler.jsonc 中添加：
{"triggers": {"crons": ["0 0 * * *", // 每天 UTC 00:00"*/15 * * * *" // 每 15 分钟]}
}
Cron 表达式格式
┌─────────── 分钟 (0-59)
│ ┌───────── 小时 (0-23)
│ │ ┌─────── 日期 (1-31)
│ │ │ ┌───── 月份 (1-12)
│ │ │ │ ┌─── 星期 (0-7, 0 和 7 都代表周日)
│ │ │ │ │
* * * * *
常用示例：
0 0 * * *- 每天午夜0 */6 * * *- 每 6 小时0 0 * * 1- 每周一午夜0 0 1 * *- 每月 1 号午夜
处理 Cron 事件
export default {async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {console.log('Cron job triggered at:', new Date(event.scheduledTime));// 执行定时任务await performScheduledTask(env);}
}
测试 Cron 触发器（本地）
curl "http://localhost:8787/__scheduled?cron=0+0+*+*+*"
查看触发器列表
npx wrangler triggers list
日志与监控
实时日志
npx wrangler tail
按状态过滤：
npx wrangler tail --status=error
按请求方法过滤：
npx wrangler tail --method=POST
查看最近的日志
npx wrangler tail --format=pretty
最佳实践
1. 环境隔离
开发环境：
- 使用
--local标志 - 数据存储在
.wrangler/state/目录 - 环境变量在
.dev.vars文件中
生产环境：
- 使用
--remote标志 - 通过
wrangler secret put设置密钥 - 始终先备份再操作
2. 数据库迁移
# 1. 导出当前生产数据
npx wrangler d1 export my-db --remote --output=backup_$(date +%Y%m%d).sql# 2. 应用新的 schema
npx wrangler d1 execute my-db --remote --file=migrations/001_add_column.sql# 3. 验证
npx wrangler d1 execute my-db --remote --command="PRAGMA table_info(users);"
3. 部署前检查清单
4. 版本控制
wrangler.jsonc 示例：
{"name": "my-worker","main": "src/index.ts","compatibility_date": "2025-01-01","compatibility_flags": ["nodejs_compat"]
}
重要配置：
compatibility_date: 锁定 Workers 运行时行为compatibility_flags: 启用特定功能（如 Node.js 兼容）
5. 监控和告警
export default {async fetch(request: Request, env: Env, ctx: ExecutionContext) {const start = Date.now();try {const response = await handleRequest(request, env);// 记录性能指标const duration = Date.now() - start;console.log(`Request processed in ${duration}ms`);return response;} catch (error) {// 记录错误console.error('Request failed:', error);// 可以集成第三方监控服务（如 Sentry）// await reportError(error, env);return new Response('Internal Server Error', { status: 500 });}}
}
6. 常用命令别名
在 package.json 中添加脚本：
{"scripts": {"dev": "wrangler dev","deploy": "wrangler deploy","tail": "wrangler tail","db:local": "wrangler d1 execute my-db --local --file=schema.sql","db:remote": "wrangler d1 execute my-db --remote --file=schema.sql"}
}
使用：
npm run dev
npm run deploy
故障排查
问题 1: 本地数据库找不到
症状： Error: no such table: users
解决：
npx wrangler d1 execute my-db --local --file=schema.sql
问题 2: Secret 未生效
症状： env.API_KEY is undefined
解决：
- 生产环境：
npx wrangler secret put API_KEY - 本地环境：检查
.dev.vars文件是否存在
问题 3: 部署后代码未更新
解决：
- 清除浏览器缓存（Ctrl+F5）
- 检查部署日志：
npx wrangler deployments list - 查看实时日志：
npx wrangler tail
问题 4: Cron 任务未触发
排查：
- 检查
wrangler.jsonc中的 cron 表达式 - 确认已部署到生产环境（本地不支持 cron）
- 查看日志：
npx wrangler tail
参考资源
- Wrangler 官方文档
- D1 数据库文档
- R2 存储文档
- Workers 运行时 API
- Cron 触发器文档
总结
Wrangler 是开发 Cloudflare Workers 应用的核心工具。掌握以下核心命令即可覆盖大部分场景：
| 功能 | 命令 |
|---|---|
| 本地开发 | npx wrangler dev |
| 部署 | npx wrangler deploy |
| 数据库操作 | npx wrangler d1 execute <db> --remote --file=schema.sql |
| 配置密钥 | npx wrangler secret put <KEY> |
| 查看日志 | npx wrangler tail |
| 导出数据 | npx wrangler d1 export <db> --remote --output=backup.sql |
建议在项目中保留一份简化的命令速查表，方便团队成员快速上手。