15分钟上手 Wrangler：部署首个边缘 API

开篇：别为了简单的 Webhook 去租服务器

做业务开发时经常遇到轻量级需求：加个 Webhook 通知、定时拉取第三方数据、简单的格式转换接口。按传统做法，得申请云主机、安装 Docker、配置 Nginx、处理域名备案。流程走完，需求早已过期。

如果你也想摆脱这种繁琐的部署模式，这篇教程提供了一条更轻量的路径。

Cloudflare Workers 凭借全球 300+ 边缘节点和近乎零冷启动的特性，成为轻量级服务的首选方案。wrangler 是它的官方 CLI 工具，底层由 Rust 编写，主打体积小、配置极简、开发体验丝滑。

本篇带你走完完整流程：环境搭建 → 本地热更新调试 → 路由与加密密钥配置 → 一键全球部署。全程 15 分钟，无需接触传统服务器。

前置条件

动手前确认环境满足以下要求：

• Cloudflare 账号：免费版即可，用于后续鉴权和部署目标域名分配。
• Node.js 18+：Cloudflare Workers 全面拥抱现代 JavaScript 标准，低版本会遇到兼容性问题。推荐用 nvm 管理多版本。
• 终端操作基础：熟悉目录切换、文件查看等基本命令，了解 TypeScript/JavaScript 基础语法。
• npm 或 pnpm：用于全局安装 CLI 工具及后续依赖管理。

快速上手：从安装到跑通本地环境

1. 安装 Wrangler CLI

官方推荐通过 npm 全局安装，省心且自动处理依赖关系：

npm install -g wrangler
wrangler --version

安装完成后，输入 wrangler --version 看到版本号即表示成功。Wrangler 虽由 Rust 编写核心逻辑，但外围包含了大量 Node.js 生态的构建和模拟工具链，npm 分发能无缝对接现有的开发习惯。

2. 账号授权

CLI 需要权限才能操作 Cloudflare 资源：

wrangler login

终端会提示打开浏览器，点击 Allow 授权后，控制台会显示登录成功的邮箱地址。其本质是让 CLI 获取 OAuth Token 并安全存储在本地配置目录，后续所有部署命令都会携带这个身份凭证与云端交互。

3. 初始化项目

一条命令生成标准项目骨架：

wrangler init my-edge-api && cd my-edge-api

选择 TypeScript 模板。生成后的目录包含 src/index.ts（Worker 执行入口）、wrangler.toml（集中式配置文件）和 package.json。

wrangler.toml 取代了过去分散的 .env 文件和部署脚本。路由规则、兼容层开关、KV/D1 数据库绑定、构建参数全部集中在一个文件中管理，真正做到配置即代码。

4. 启动本地开发

进入项目根目录执行：

wrangler dev

终端会启动本地模拟服务器（默认运行在 http://localhost:8787）。浏览器访问该地址能看到默认的 Hello World 响应。wrangler dev 不是简单的静态文件服务器，它在本地完整模拟了 Cloudflare Workers 的 V8 隔离运行环境，支持热重载。保存代码后终端自动刷新，开发体验流畅高效。

实战示例：部署带鉴权的查询 API

1. 编写路由逻辑

打开 src/index.ts，用零依赖方式实现带鉴权的路由分发：

export interface Env {
  API_SECRET: string;
}

const router = {
  '/query': async (request: Request, env: Env) => {
    const url = new URL(request.url);
    const key = url.searchParams.get('key');
    
    if (key !== env.API_SECRET) {
      return new Response('Unauthorized', { status: 401 });
    }

    const data = { status: 'ok', timestamp: Date.now(), region: 'Global Edge' };
    return new Response(JSON.stringify(data), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);
    const handler = router[url.pathname as keyof typeof router];
    return handler ? handler(request, env) : new Response('Not Found', { status: 404 });
  }
};

核心设计：

• Env 接口定义运行时注入的外部变量，TypeScript 会在访问环境变量时提供完整的智能提示和类型检查，避免拼写错误。
• fetch 函数是 Workers 的标准请求入口，每次 HTTP 请求都会触发。使用对象路由表替代 Express 等重型框架，因为 Workers 体积越小、依赖越少，冷启动速度越快，边缘节点响应延迟越低。
• 密钥校验逻辑放在路由内部，避免硬编码到代码库中推送到公开仓库导致泄露。

2. 配置环境变量

在 wrangler.toml 末尾追加变量声明：

[vars]
API_SECRET = "my-super-secret-key-123"

运行 wrangler dev 时，Wrangler 会自动读取 [vars] 配置块并注入到处理器的 env 参数中。配置优先的设计让密钥管理与代码分离，不同环境只需切换对应配置文件即可。

3. 一键部署到边缘网络

确认本地访问 http://localhost:8787/query?key=my-super-secret-key-123 能返回正常 JSON 数据后，直接执行部署命令：

wrangler deploy

控制台会显示文件上传、代码压缩、发布进度。部署完成后，终端会返回分配到的 *.workers.dev 域名。

直接在浏览器或 API 测试工具中访问该线上地址。Workers 运行在距离用户最近的 Cloudflare 边缘节点，请求无需穿透到源站，延迟极低且全球访问速度保持一致。

常见问题排查

1. 部署后报 502 或 Worker 运行异常：绝大多数情况是代码中引入了 Node.js 原生模块（如 fs、path、crypto）。Workers 基于标准 Web API 运行，不支持直接 import Node 内置库。确实需要使用时，在 wrangler.toml 中开启 nodejs_compat 兼容层即可。
2. 部署接口报 401 权限错误：wrangler login 获取的 OAuth Token 存在有效期。长时间未执行部署操作后凭证可能过期，重新运行 login 命令刷新本地凭据即可解决。
3. 免费版请求额度管控：Cloudflare 免费套餐每天提供 10 万次请求配额。个人项目、内部工具或低频 API 完全够用。若接口可能被高频调用或遭遇爬虫，建议在代码层增加基础 Rate Limit 逻辑，或后续接入 Cloudflare 缓存层降低回源压力。

总结与延伸

本篇走完了 Serverless 边缘开发的完整闭环：安装官方 CLI → 本地环境模拟调试 → 编写无状态路由逻辑 → 注入环境变量 → 一键发布至全球边缘网络。现代边缘计算平台已经屏蔽了底层服务器运维工作，开发者只需聚焦业务逻辑实现。

上手流程跑通后，可进一步探索 Cloudflare 生态的 D1 关系型数据库 和 R2 对象存储。将今天的无状态 API 与持久化存储能力结合，无需租用传统云服务器，即可搭建具备数据读写能力的完整全栈应用。

开发环境已就位，现在去部署你的第一个边缘服务。