Wrangler 与本地开发

这一课你将能做到

1. 用 Wrangler CLI 完成初始化、本地调试、部署、日志追踪的全流程
2. 配置 wrangler.toml（或 .dev.vars）绑定 KV、R2、D1 等本地服务绑定
3. 解释 Miniflare 在本地开发中扮演的角色，并能处理本地与线上的行为差异

为什么要学

你总不能每次改一个 console.log 就 wrangler deploy 一次吧——部署到全球节点虽然快，但开发阶段太慢了。Wrangler + Miniflare 让你在本地拥有一套「伪边缘」环境：同样的 V8 Isolate、同样的 Fetch 标准、同样的绑定接口，但跑在你本机 8787 端口上。

人话：Wrangler 就是 Workers 的 npm + docker-compose + kubectl。没有它，你连项目都初始化不了、本地都跑不起来、日志都看不到。

先建立图像

┌──────────────────────────────────────────────┐
│  你的 VS Code                                 │
│  ├── src/index.ts                             │
│  ├── wrangler.toml    <── 配置绑定/环境/路由  │
│  ├── .dev.vars        <── 本地密钥（不上传）   │
│  └── package.json                             │
└─────────────────────┬────────────────────────┘
                      │ npx wrangler dev
                      ▼
┌──────────────────────────────────────────────┐
│  Miniflare (本地 Workers 运行时模拟器)         │
│  ├── 模拟 V8 Isolate                          │
│  ├── 模拟 KV / R2 / D1 / Queue 绑定           │
│  └── 监听 localhost:8787                      │
└──────────────────────────────────────────────┘

跟着做

步骤 1：确认 Wrangler 版本

npx wrangler --version
# 建议 >= 3.x，旧版配置格式不同

如果全局安装过旧版：

npm uninstall -g wrangler
npm install -g wrangler

步骤 2：创建项目（Hono 路由版）

npm create cloudflare@latest my-api -- --template hono --ts true
cd my-api
npm install

Hono 是一个轻量、类 Express 的边缘路由框架，在 Workers 社区很流行。项目结构：

├── src/
│   └── index.ts
├── wrangler.toml
├── package.json
└── tsconfig.json

步骤 3：wrangler.toml 核心字段解读

name = "my-api"
main = "src/index.ts"
compatibility_date = "2024-09-01"
compatibility_flags = ["nodejs_compat"]

# 环境变量（非密钥，可以明文写）
[vars]
ENVIRONMENT = "staging"
RATE_LIMIT = "100"

# KV 绑定
[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxx"

# R2 绑定
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "cdn-uploads"

# D1 绑定
[[d1_databases]]
binding = "DB"
database_name = "app-db"
database_id = "yyyy-yyyy-yyyy"