Wrangler实战：从安装到部署Cloudflare Worker
本文手把手带你使用Wrangler CLI完成Cloudflare Worker项目的全流程：环境安装、项目初始化、本地调试、配置解析到云端部署。学完后你能独立搭建并上线一个全球可访问的Serverless API，摆脱繁琐的服务器运维，快速掌握边缘计算开发技能。
Wrangler实战：从安装到部署Cloudflare Worker
为什么选择边缘计算
传统后端部署往往需要操心服务器扩容、CDN配置、全球节点分布这些运维问题。接触Cloudflare Workers后，用Wrangler这个CLI工具，几分钟就能把轻量级API部署到全球275+边缘节点，延迟表现让人印象深刻。
如果你也想用最少代码跑一个全球可用的API或中间件，这篇教程带你走完完整流程。
环境准备
开始前准备好以下工具：
- Node.js 18+：Wrangler基于Node.js生态，推荐用
nvm管理版本 - npm或pnpm：包管理工具，pnpm速度更快且节省磁盘
- Cloudflare账号：免费注册即可，部署时需要登录验证
- JavaScript/TypeScript基础：Worker运行时兼容V8，语法与浏览器端写法一致
安装Wrangler
打开终端执行全局安装：
bash
npm install -g wrangler
## 或使用pnpm
pnpm add -g wrangler安装完成后验证版本：
bash
wrangler --versionWrangler是Cloudflare官方命令行工具，集成了项目创建、本地服务器启动、配置校验和云端部署能力，装好后所有操作都在一个工具内完成。
登录Cloudflare
安装完成后需要授权Wrangler访问你的账号：
bash
wrangler login执行后自动打开浏览器，登录Cloudflare并授权Wrangler。授权成功后终端显示Successfully logged in。这相当于给CLI发放通行证，后续部署无需重复输入密码。
初始化项目
创建干净的目录并初始化：
bash
mkdir my-first-worker && cd my-first-worker
wrangler init初始化过程会询问：
- 项目类型：选择
Hello World模板 - 是否使用TypeScript：推荐选
yes - 是否创建Git仓库：按需选择
完成后目录结构如下：
my-first-worker/
├── src/
│ └── index.ts # Worker入口文件
├── package.json
├── tsconfig.json
└── wrangler.toml # 核心配置文件打开src/index.ts可以看到：
typescript
export interface Env {
// 环境变量定义
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
return new Response("Hello from Cloudflare Workers!");
},
};Workers的编程模型与Fetch API一致——接收Request对象，处理后返回Response对象。没有Express、没有路由库，纯粹的请求-响应循环让代码非常容易理解。
本地开发调试
开发阶段无需每次修改都部署到云端，Wrangler提供本地开发服务器：
bash
wrangler dev启动后终端显示本地访问地址：
⛅️ wrangler x.x.x
───────────────────
Your worker has access to https://localhost:8787浏览器打开http://localhost:8787即可看到输出。修改src/index.ts时Wrangler会自动监听文件变化并热重载，底层使用本地模拟的Workers Runtime，体验与Vite或Nodemon的watch模式类似。
理解wrangler.toml配置
打开wrangler.toml会看到核心配置：
toml
name = "my-first-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
## [vars] # 环境变量
## MY_VAR = "something"
## [[kv_namespaces]] # KV存储
## binding = "MY_KV"
## id = "xxxxxxxx"关键字段说明：
name：Worker名称，部署后作为子域名一部分（如my-first-worker.<账号>.workers.dev）main：入口文件路径，指定编译起点compatibility_date：重要配置！决定代码使用哪个版本的Workers Runtime API。建议设置为当前或最近日期，确保使用最新特性且避免兼容性问题[vars]：定义环境变量（API Key、数据库连接等），运行时通过env.MY_VAR访问[[kv_namespaces]]：绑定Cloudflare KV存储（类似Redis的键值对数据库）
配置完成后，部署前可用wrangler deploy --dry-run校验合法性。
实战：部署带路由的JSON API
编写真正可用的API，修改src/index.ts：
typescript
export default {
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url);
const path = url.pathname;
if (path === "/api/time") {
return new Response(
JSON.stringify({ now: new Date().toISOString(), server: "Cloudflare Worker" }),
{ headers: { "Content-Type": "application/json" } }
);
}
if (path === "/api/echo" && request.method === "POST") {
const body = await request.json();
return new Response(
JSON.stringify({ received: body }),
{ headers: { "Content-Type": "application/json" } }
);
}
return new Response("Not Found", { status: 404 });
},
};本地验证无误后执行部署：
bash
wrangler deploy首次部署会生成对应Worker并自动构建上传。成功后获得公网URL：
Published my-first-worker (x.xx s)
https://my-first-worker.<你的账号>.workers.dev用浏览器或curl访问https://<你的URL>/api/time即可获取UTC时间戳。
Wrangler部署本质是将TypeScript代码编译为符合Workers规范的格式，打包上传到Cloudflare边缘网络。全程无需配置Docker、Nginx或反向代理。
常见问题与踩坑提醒
wrangler dev启动报错Port 8787 already in use
端口被占用，可用wrangler dev --port 9000指定其他端口，或用lsof -i :8787查看并结束占用进程。
TypeScript编译找不到Request/Response类型
Workers Runtime提供这些全局类型，但IDE可能不认识。安装类型定义解决：
bash
npm install -D @cloudflare/workers-types然后在tsconfig.json的types字段添加"@cloudflare/workers-types"。
部署失败Error: Missing account ID
通常因多账号或登录状态过期导致。重新执行wrangler login，或在wrangler.toml手动指定account_id。
本地wrangler dev与线上行为不一致
本地毕竟是模拟环境，高级功能（Durable Objects、Queue等）可能不完全支持。建议定期用wrangler deploy部署测试。
后续探索
完成部署后可继续探索：
- 在
wrangler.toml配置环境变量和Secrets - 接入Cloudflare KV或D1数据库，让Worker具备状态管理能力
- 使用
wrangler pages部署全栈应用 - 研究Middleware模式，实现请求拦截和鉴权
Cloudflare Workers生态持续成长，Wrangler作为官方CLI工具体验已非常成熟。花一个周末跑通这套流程，你会收获一种全新的后端开发方式。