Wrangler CLI 工具完整使用指南

下面给你一份「从 0 到可用」的 Wrangler 安装与用法指南,按步骤走,10–15 分钟就能跑通一个 Cloudflare Worker。

Wrangler 是什么?

Wrangler = Cloudflare Workers 官方 CLI 工具

它用来做 4 件事:

登录 Cloudflare 账号
创建 Worker 项目
本地调试 Worker
部署 Worker 到线上

安装 Wrangler

前置条件

Node.js ≥ 18(建议 LTS)
npm / pnpm / yarn 任一

检查版本:

node -v
npm -v

全局安装(最常见)

npm install -g wrangler

验证是否成功:

wrangler -v

能看到版本号即成功。

(可选)使用 npx(无需全局安装)

npx wrangler -v

适合不想污染全局环境。

登录 Cloudflare 账号

wrangler login

流程:

自动打开浏览器
登录 Cloudflare
授权 Wrangler

成功后终端会显示:

Successfully logged in.

创建一个 Worker 项目

方式一:交互式创建(最推荐)

wrangler init my-worker

过程中建议选择:

✔ What type of worker? → Fetch handler
✔ Language → JavaScript or TypeScript
✔ Git → Yes(可选)
✔ Install deps → Yes

生成结构大致是:

my-worker/
├─ src/
│  └─ index.js
├─ wrangler.toml
└─ package.json

方式二:快速创建(无交互)

wrangler init my-worker --yes

最小可用 Worker 示例

src/index.js:

1
export default {
2
  async fetch(request) {
3
    return new Response('Hello from Worker')
4
  }
5
}

本地运行(非常重要)

wrangler dev

你会看到类似:

Listening on http://localhost:8787

浏览器访问:

http://localhost:8787

本地可调试
支持 POST / OPTIONS / Headers
非常适合你现在调 CORS / 表单接口

部署到线上

wrangler deploy

成功后你会看到:

Published my-worker
https://my-worker.your-account.workers.dev

这就是你的 API 地址。

wrangler.toml 核心配置说明

一个最常见的配置:

1
name = "my-worker"
2
main = "src/index.js"
3
compatibility_date = "2024-12-01"
4

5
[vars]
6
ENV = "production"

绑定 Secret(非常重要)

比如你的 Resend Key:

wrangler secret put RESEND_API_KEY

使用方式:

1
env.RESEND_API_KEY

与你当前项目强相关的用法

本地调试 CORS / 表单接口

wrangler dev

然后前端请求:

http://localhost:8787/api/contact

可以完全绕开线上问题。

查看 Worker 日志(排错神器)

wrangler tail

你可以看到:

请求是否进来了
Resend 返回了什么
422 / 500 的真实原因

常见错误 & 对应解决方案

1. wrangler: command not found

npm install -g wrangler

或使用:

npx wrangler

2. NOT_FOUND

原因:

Worker 名不对
没 deploy
用了旧 URL

解决:

wrangler deploy

3. 本地能跑,线上不行

原因:

Secret 没设置
CORS 不同
环境变量缺失

检查:

wrangler secret list