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"

compatibility_date 是 Workers 的「ABI 版本」：Cloudflare 会持续更新运行时，这个日期决定你的 Worker 能看到哪一天的 API 行为，避免线上突然变化。

步骤 4：本地开发

npx wrangler dev

带上本地密钥：

# .dev.vars
OPENAI_API_KEY=sk-local-test-key
JWT_SECRET=my-local-secret

npx wrangler dev

.dev.vars 不会进入 git，也不会被 deploy。线上密钥去 Dashboard → Workers & Pages → 对应 Worker → Variables 里设置，或用 wrangler secret put：

npx wrangler secret put OPENAI_API_KEY

步骤 5：查看实时日志

本地调试时终端直接输出。部署到线上后：

npx wrangler tail

这会通过 Cloudflare 的日志管道实时输出你 Worker 里的 console.log，排查生产问题必备。

步骤 6：部署

npx wrangler deploy

会输出类似 https://my-api.xxx.workers.dev。若使用自定义域名，需要在 Dashboard 设置 Routes。

步骤 7：带环境部署

npx wrangler deploy --env production

对应的 wrangler.toml：

[env.production]
name = "my-api-prod"
routes = [{ pattern = "api.mysite.com/*", custom_domain = true }]

讲清楚要点

1. Miniflare 不是真 Workers：它是本地 Node.js 实现的模拟器，绝大多数行为一致，但某些边缘特性（如 Smart Placement、部分新 API）可能行为不同。上线前务必在真实 Workers 环境测试。
2. wrangler.toml vs .dev.vars 的区别：toml 里的 vars 和绑定配置会随代码一起部署；.dev.vars 只在本地 dev 时注入，用于存储密钥和本地专属变量。
3. compatibility_date 必须设置：它决定 Workers 运行时的 API 版本。Cloudflare 的升级策略是「不破坏已有 Worker」，这个日期就是你的「冻结点」。
4. nodejs_compat 标志：允许你使用部分 Node.js API（如 Buffer、crypto、path）。不是全部 Node 模块都能用，官方维护了一个兼容列表。需要完整 Node 环境时，考虑用 Cloudflare Pages Functions + Node 构建。
5. 本地缓存和线上不一样：本地 KV 是内存中的模拟对象，重启后清空；线上 KV 是分布式存储。测试数据持久化时小心混淆。

你可能会懵的地方

• 为什么 wrangler deploy 后代码变了但行为没变？ 先看 compatibility_date 是否太旧，导致新 API 行为被冻结。也可能是浏览器 CDN 缓存了响应，加 Cache-Control: no-cache 测试。

• .dev.vars 写好了但 env.XXX 读不到？ 确认在 wrangler dev 启动前文件已存在；确认变量名拼写一致（大小写敏感）。若用 Hono，变量通过 c.env 访问而不是全局 process.env。

• TypeScript 类型报错 Cannot find name KVNamespace？ 需要在项目里安装 @cloudflare/workers-types：

  npm install -D @cloudflare/workers-types
  

  并在 tsconfig.json 的 types 数组中引入。

• 本地 wrangler dev 端口冲突？ 默认 8787。可以改：npx wrangler dev --port 3000。

• 日志刷屏太多怎么办？ wrangler tail 支持过滤级别和采样，也可以开启 Workers Analytics Logs 导出到第三方（如 Datadog、Sentry）。

错法对照

错法	问题	正解
把生产密钥写进 wrangler.toml	toml 会进 git，可能泄露	密钥用 wrangler secret put 或 .dev.vars
本地没装 @cloudflare/workers-types	TS 不认识 Env、KVNamespace 等类型	npm i -D @cloudflare/workers-types
compatibility_date 写成 2024-1-1（缺前导零）	解析失败	严格按 YYYY-MM-DD 格式
用 process.env 读环境变量	Workers 运行时无 process 对象	通过 env 参数或 c.env（Hono）访问
本地 dev 正常，部署后报错 x is not defined	线上没有 .dev.vars	用 wrangler secret put 或 Dashboard 设置变量

卡点急救

1. wrangler login 卡在终端无响应：先确认终端能访问外网；若公司网络有代理，设置 HTTPS_PROXY 环境变量再试。实在不行去 Dashboard → API Tokens → Create Token → Edit Cloudflare Workers 模板，然后用 wrangler login --browser=false + Token 方式。

2. npx wrangler dev 启动后 localhost 访问 404：检查 wrangler.toml 的 main 字段是否指向了正确的入口文件；如果用了 Hono，确认 export default app 在入口文件末尾。

3. 部署时提示 route pattern already in use：你的 routes 配置和另一个 Worker 或 Zone 冲突了。去 Dashboard → Workers & Pages → Routes 里检查已有路由，或改用 custom_domain = true 而不是通配符 *。

面试常问

• Miniflare 和真实 Workers 运行时有什么差异？ Miniflare 用 Node.js 模拟 V8 Isolate 和绑定，本地开发时缺少部分边缘特性（如真正的 Smart Placement、某些 KV 一致性行为）。绝大多数标准 Web API 行为一致，但生产上线前必须在真实环境验证。

• 如何安全地管理不同环境的密钥？ 开发环境用 .dev.vars（不提交 git）；生产/预发环境用 wrangler secret put 或 Dashboard Variables。wrangler.toml 的 [env.xxx] 可以隔离不同环境的绑定和路由，配合 --env 参数部署。

• compatibility_date 为什么重要？ Cloudflare 持续在 Workers 运行时里加入新 API 和 bugfix，但不会破坏已部署的 Worker。compatibility_date 就是你和平台的「契约日期」，确保你今天写的代码在一年后不会因为运行时升级而行为突变。

自测三问

1. .dev.vars 和 wrangler.toml 的 [vars] 有什么区别？各适合存什么？
2. compatibility_date 和 compatibility_flags 分别控制什么？
3. 如果本地 dev 一切正常但 deploy 后变量丢失，最可能的原因是什么？

小结一句话

Wrangler 是 Workers 的全能 CLI，Miniflare 提供本地模拟环境；掌握 wrangler.toml、.dev.vars、secret 管理和 wrangler tail，你就拥有了一整套边缘开发的本地到生产工具链。

延伸

• Wrangler CLI 官方文档
• Miniflare 本地开发指南
• 下一课：Workers 核心，深入请求生命周期、Fetch Handler、路由与中间件。