Wrangler CLI 工具完整使用指南

n8n工作流分享：商业级别的5个实用自动化工作流分享，诚意满满

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

Wrangler 是什么?

Wrangler = Cloudflare Workers 官方 CLI 工具

它用来做 4 件事:

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

安装 Wrangler

前置条件

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

检查版本:

bash 复制代码

node -v
npm -v

全局安装(最常见)

bash 复制代码

npm install -g wrangler

验证是否成功:

bash 复制代码

wrangler -v

能看到版本号即成功。

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

bash 复制代码

npx wrangler -v

适合不想污染全局环境。

登录 Cloudflare 账号

bash 复制代码

wrangler login

流程:

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

成功后终端会显示:

text 复制代码

Successfully logged in.

创建一个 Worker 项目

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

bash 复制代码

wrangler init my-worker

过程中建议选择:

text 复制代码

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

生成结构大致是:

text 复制代码

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

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

bash 复制代码

wrangler init my-worker --yes

最小可用 Worker 示例

src/index.js:

js 复制代码

export default {
  async fetch(request) {
    return new Response('Hello from Worker')
  }
}

本地运行(非常重要)

bash 复制代码

wrangler dev

你会看到类似:

text 复制代码

Listening on http://localhost:8787

浏览器访问:

text 复制代码

http://localhost:8787

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

部署到线上

bash 复制代码

wrangler deploy

成功后你会看到:

text 复制代码

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

这就是你的 API 地址。

wrangler.toml 核心配置说明

一个最常见的配置:

toml 复制代码

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

[vars]
ENV = "production"

绑定 Secret(非常重要)

比如你的 Resend Key:

bash 复制代码

wrangler secret put RESEND_API_KEY

使用方式:

js 复制代码

env.RESEND_API_KEY

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

本地调试 CORS / 表单接口

bash 复制代码

wrangler dev

然后前端请求:

text 复制代码

http://localhost:8787/api/contact

可以完全绕开线上问题。

查看 Worker 日志(排错神器)

bash 复制代码

wrangler tail

你可以看到:

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

常见错误 & 对应解决方案

1. wrangler: command not found

bash 复制代码

npm install -g wrangler

或使用:

bash 复制代码

npx wrangler

2. NOT_FOUND

原因:

Worker 名不对
没 deploy
用了旧 URL

解决:

bash 复制代码

wrangler deploy

3. 本地能跑,线上不行

原因:

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

检查:

bash 复制代码

wrangler secret list

Wrangler CLI 工具完整使用指南

n8n工作流分享：商业级别的5个实用自动化工作流分享，诚意满满

Wrangler 是什么?

安装 Wrangler

前置条件

全局安装(最常见)

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

登录 Cloudflare 账号

创建一个 Worker 项目

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

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

最小可用 Worker 示例

本地运行(非常重要)

部署到线上

wrangler.toml 核心配置说明

绑定 Secret(非常重要)

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

本地调试 CORS / 表单接口

查看 Worker 日志(排错神器)

常见错误 & 对应解决方案

1. wrangler: command not found

2. NOT_FOUND

3. 本地能跑,线上不行

推荐你现在的"正确工作流"