本指南针对希望在 Cloudflare 边缘构建「数字后花园」或自动化工具的前端、后端开发者，系统阐述从本地快速迭代、资源绑定、调试定位，到通过 GitHub Actions 实现推送即部署的完整流程。掌握文中命令与配置，即可在本地放心开发、在云端安全发布，并实现 CI/CD 自动化。
Wrangler 命令全景图
核心高频命令
| 命令 | 说明 | 常用场景 |
|---|
wrangler login | 账户授权 | 首次使用或更换设备时执行 |
wrangler init [name] | 初始化项目 | 快速生成目录结构和 wrangler.toml |
wrangler dev | 本地开发服务器 | 实时预览代码修改，支持热更新 |
wrangler deploy | 部署到生产环境 | 将本地代码分发至全球边缘节点 |
wrangler tail | 实时日志流 | 监控线上 Workers 的运行状态和报错 |
wrangler whoami | 账户信息查询 | 检查当前登录的账户 ID 和权限 |
核心配置文件：wrangler.toml
配置示例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| name = "my-worker-app"
main = "src/index.js"
compatibility_date = "2026-05-06"
# 1. 环境变量（明文）
[vars]
ENVIRONMENT = "production"
API_URL = "https://api.17you.com"
# 2. D1 数据库绑定（留言板系统核心）
[[d1_databases]]
binding = "DB"
database_name = "guestbook_db"
database_id = "xxxx-xxxx-xxxx"
# 3. R2 存储池绑定（适合存放图片或大型静态文件）
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-assets"
# 4. 定时任务（自动化采集必备）
[triggers]
crons = ["*/30 * * * *"] # 每 30 分钟运行一次
|
开发与调试流程
本地模拟（Local-First）
1
2
| # 开启本地 D1 模拟并持久化数据到 .wrangler 文件夹
npx wrangler dev --local --persist
|
- 按 b 键可在默认浏览器中自动打开预览链接；
- 按 x 键可停止本地服务器。
线上追踪（Remote Tail）
实时输出线上节点的 console.log 与异常信息，帮助快速定位 500 等生产错误。
资源管理
D1 数据库操作
1
| npx wrangler d1 execute <db_name> --file=./schema.sql
|
1
| npx wrangler d1 export <db_name> --remote --output=./backup.sql
|
KV 键值对操作
1
| npx wrangler kv:key put --binding=MY_KV "key" "value"
|
安全与权限优化
交互式密钥设置
1
| npx wrangler secret put SECRET_TOKEN
|
运行后会提示输入值，Wrangler 将在 Cloudflare 侧加密存储，可通过 env.SECRET_TOKEN 在代码中安全读取。
高级自动化场景
工作流示例
1
2
3
4
5
6
7
8
9
10
11
12
| name: Deploy Worker
on: [push]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
配合 GitHub 仓库的 Secrets，实现「推送即上线」的完整 CI/CD 流程。
避坑指南（Windows 11 专供）
- 路径长度：将项目放在根目录较浅的路径（如
D:\Code\Project），避免 node_modules 超出 Windows 长度限制； - 端口冲突：默认
8787 被占用时，使用 npx wrangler dev --port 9000 替换端口； - 脚本执行策略：PowerShell 报错时执行以下命令以允许运行脚本：
1
| Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
更新日志
- 2026-05-07：统一标题层级、优化段落间距、统一列表与标点、补充引言段落、添加更新日志。
