Cloudflare Workers项目部署和wrangler命令使用

最近，xiaoz 在开发一个 HTTP 邮件发送服务。项目本身不复杂，图个省事，打算部署到 Cloudflare Workers 上。虽然中间遇到了一点小问题，但在 AI 的帮助下很快解决了。由于是第一次用 wrangler 命令部署，不太熟悉，踩了些坑，顺手用这篇文章记录一下。

什么是wrangler？

Wrangler 是Cloudflare官方推出的一个让你在命令行里一键部署和管理 Cloudflare Workers 工具，如果您在开发适配Cloudflare Workers的程序，Wrangler工具几乎是绕不开的。

安装wrangler

使用bun或者pnpm均可安装wrangler，命令如下：

# 使用bun安装wrangler
bun install -g wrangler
# 使用pnpm安装wrangler
pnpm install -g wrangler

安装完毕后输入wrangler --version查看版本号。

Cloudflare Workers项目配置

在适配Cloudflare Workers项目时，根目录下存在一个配置文件wrangler.jsonc里面可能包含如下信息：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "zsend",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-17",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "zsend",
      "database_id": "29364a4e-08d4-420f-a06f-f8db95041113"
    }
  ],
  "dev": {
    "ip": "0.0.0.0",
    "port": 8000
  }
}

* name：Workers 项目的名称，会用于 Cloudflare 仪表盘上的标识，也用于本地开发时的项目识别。
* main:入口文件路径，即 Worker 的脚本主文件（这里是 src/index.ts），Wrangler 会打包并部署该文件。
* compatibility_date：指定 Worker 运行时兼容的日期，用于启用该日期之后的新功能或修复，确保行为的一致性。
* compatibility_flags：显式开启某些实验性或特定版本的运行时特性，例如 ["nodejs_compat"] 会启用 Node.js 兼容层。
* d1_databases：配置项目关联的 Cloudflare D1 数据库，是一个数组。
* dev：本地开发环境（wrangler dev）的配置项

同时也可以在wrangler.jsonc中配置环境变量参数，但一般不建议通过修改这个配置来设置环境变量，一是不安全，二是不适合开源和分发代码。

使用wrangler命令

需要部署Workers项目，我们需要使用wrangler命令完成登录授权，如果您的操作系统带有图形界面，可以直接使用wrangler login完成。

但如果在不带图形界面的Linux终端中，我们可以通过API方式来完成认证，命令如下：

# 设置API认证
echo 'export CLOUDFLARE_API_TOKEN=xxx' >> ~/.bashrc
# 使其生效
source ~/.bashrc

> 提示：API Token需要在Cloudflare后台完成并给予对应权限！

然后我们可以使用wrangler whoami查看是否认证成功。

设置项目参数

上面已经提到一般不推荐在wrangler.jsonc中配置参数，推荐的做法是使用wrangler secret命令，比如你想设置一个TOKEN环境变量，使用下面的命令：

# 新建一个TOKEN环境变量
wrangler secret put TOKEN

然后可以使用wrangler secret list列出所有设置的变量列表，或者在网页版的【设置】选项里面也能看到。

部署项目

直接参考下面的命令就行了：

# 部署到默认环境
wrangler deploy

# 列出所有版本
wrangler versions list

# 回滚到指定版本
wrangler rollback 

# 查看当前部署的版本详情
wrangler versions view 

然后域名绑定啥的，自行去Cloudflare Workers项目中设置即可。

结语

个人觉得Cloudflare Workers项目的开发和部署流程还是偏繁琐的，而且第一次比较容易踩坑，但胜在Cloudflare Workers提供了友好的免费额度，可以让一些小型项目0成本跑起来，还要什么自行车呢。