Cloudflare Workers 教程

一、简介

Cloudflare Workers 是 Cloudflare 推出的 Serverless（无服务器）边缘计算平台，它允许开发者直接在 Cloudflare 全球数百个边缘节点运行 JavaScript、TypeScript、Python（Beta）等代码，而无需购买服务器、配置 Nginx 或维护容器。

Cloudflare 在全球拥有大量边缘节点。用户访问资源时请求会分配到离用户最近的边缘Worker节点上，提供最低的延迟。

在 Cloudflare Workers 上，你不需要买服务器、安装Linux、配置Nginx等一系列操作，你只需要通过 Cloudflare 提供的工具 wrangler，即可将你的代码部署上云。

二、Cloudflare Workers 能干什么

Cloudflare Workers 给到的免费额度非常慷慨，且基本上几乎所有 HTTP 请求相关的事情都可以做

免费计划

资源 免费额度 说明
请求数 每天 100,000 次 约每月 300 万次
CPU 时间 每次请求 10ms 足够大多数场景
Workers KV（键值存储） 读取 10 万/天、写入 1000/天、存储 1GB 轻量缓存足够
D1 数据库 读取 500 万行/天、写入 10 万行/天、存储 5GB 小型应用足够
静态资源 无限制 图片、CSS、JS 等不计费
子请求 不计费 从 Worker 发起的请求免费

适合的场景

场景 说明 示例
API 服务 RESTful API 系统后端
API 代理/网关 转发请求、添加 CORS 头、处理跨域 反向代理、API 代理
边缘计算处理 图片裁剪压缩、地理位置路由 提供一定的边缘计算能力
AI 能力 Cloudflare 提供 Workers AI 调用大模型进行回答
身份认证 JWT、OAuth、OIDC、SAML 统一认证网关
Webhook 接收并处理第三方通知 发送企业微信

运行套件

Workers 可以绑定一些 Cloudflare 提供的有免费额度的开发套件工具进行更完整的后端开发

服务 作用
Workers 编写业务逻辑
KV 全局 Key-Value 缓存
R2 对象存储（S3 兼容）
D1 SQLite 数据库
Durable Objects 有状态对象，适合聊天室、协作等场景
Queues 消息队列
Vectorize 向量数据库
Workers AI AI 模型推理
Hyperdrive 数据库连接加速
Browser Rendering 无头浏览器渲染

三、Cloudflare Workers 开发环境搭建

前置要求

  1. Cloudflare 账号

  2. 本地开发环境

    • Node.js >= 18.0.0
    • npm 或 pnpm
    • Git

安装 Wrangler CLI

Wrangler 是 Cloudflare 官方的命令行工具，用于开发、测试和部署 Workers。

1
2
3
4
5
6
7
8
# 进入项目目录
cd my-worker

# 全局安装
npm install -g wrangler

# 或使用 npx（推荐，无需全局安装）
npx wrangler --version

登录 Cloudflare

1
npx wrangler login

这会打开浏览器，授权 Wrangler 访问你的 Cloudflare 账号。

创建第一个项目

1
2
3
4
5
6
7
8
9
# 使用官方脚手架创建项目
npm create cloudflare@latest -- my-first-worker

# 按提示选择：
# - 选择 "Hello World" example
# - 选择 "Worker only"
# - 选择 JavaScript 或 TypeScript
# - 是否启用 git：Yes
# - 是否立即部署：No（先本地测试）

项目结构

1
2
3
4
5
6
my-first-worker/
├── src/
│   └── index.js      # Worker 代码
├── wrangler.toml     # 配置文件（或 wrangler.jsonc）
├── package.json
└── node_modules/

核心配置文件 wrangler.toml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
name = "my-worker"                           # Worker 名称，也是访问路径
main = "src/index.ts"                        # 入口文件
compatibility_date = "2024-09-23"            # 日期必须不早于这一天
compatibility_flags = ["nodejs_compat"]      # 让 Cloudflare Workers 运行环境支持 Node.js 标准库中的 API

# AI 绑定
[ai]
binding = "AI"

# D1 数据库
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "your-database-id"

# KV 缓存
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

# R2 存储
[[r2_buckets]]
binding = "FILES"
bucket_name = "your-files"

# 环境变量
[vars]
JWT_SECRET = "your-jwt-secret"

# 开发环境配置
[dev]
port = 8787
local_protocol = "http"

# Cron 定时任务
[triggers]
crons = ["0 0 * * *"]  # 每天 UTC 00:00 执行（北京时间 08:00）

# 路由配置（可选）
# routes = [
#   { pattern = "api.example.com/*", zone_name = "example.com" }
# ]

本地测试

1
2
3
4
5
6
# 启动本地开发服务器
cd my-worker
wrangler dev

# 输出：
# Ready on http://localhost:8787

部署到生产环境

1
2
3
4
5
wrangler deploy

# 输出：
# ✨ Success! Uploaded my-worker (1.23 sec)
# https://my-worker.你的子域名.workers.dev

记录这个 URL，这是你的 API 地址。

四、Cloudflare Workers 核心套件创建

创建 D1 数据库

1
2
3
4
5
6
7
8
9
# 创建数据库
wrangler d1 create my-db

# 会输出类似这样的内容：
# ✅ Successfully created DB 'my-db'
# [[d1_databases]]
# binding = "DB"
# database_name = "my-db"
# database_id = "xxxx-xxxx-xxxx-xxxx-xxxx"

复制输出的 database_id，更新到 wrangler.toml 文件中：

1
2
3
4
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "你的-database-id"  # 替换这里

创建 KV 命名空间

1
2
3
4
5
6
7
wrangler kv namespace create CACHE

# 会输出：
# ✅ Created new KV namespace with title "my-worker-CACHE"
# [[kv_namespaces]]
# binding = "CACHE"
# id = "xxxx"

复制输出的 id，更新到 wrangler.toml：

1
2
3
[[kv_namespaces]]
binding = "CACHE"
id = "你的-kv-id"  # 替换这里

创建 R2 存储桶

1
2
3
4
wrangler r2 bucket create my-files

# 输出：
# ✅ Created bucket 'my-files'

初始化数据库

1
2
3
4
5
6
7
# 运行 SQL schema
wrangler d1 execute my-db --file=./schema.sql --remote
# 本地开发时也可以在本地创建模拟的数据库
wrangler d1 execute my-db --file=./schema.sql --local

# 输出：
# ✅ Successfully executed SQL against my-db

五、Cloudflare Workers 部署与运维

自定义域名

Workers 中也能像 Pages 中一样设置自定义域名，步骤为：

  1. 进入 Workers 页面，选择你的 Worker
  2. 点击 “域” → “添加域名”
  3. Cloudflare 会自动配置DNS和HTTPS证书

监控与日志

1
2
3
4
5
# 实时查看日志
npx wrangler tail

# 带过滤器
npx wrangler tail --format pretty --status error

在 Dashboard 中可以查看：

  • 请求量统计
  • 错误率
  • CPU 使用情况
  • 地理分布

自动化部署

等前期工作结束，项目也趋于稳定状态后，就可以不通过 wrangler deploy 部署了，而是可以通过推送到GitHub仓库实现自动部署，原理和 Pages 一样

总结

Cloudflare Workers 可以理解为一个运行在全球边缘节点上的 Serverless JavaScript/TypeScript 运行时，它将 CDN、边缘计算、API 网关、缓存、AI 推理、对象存储和数据库能力整合在同一平台中。

例如：

  • Cloudflare Workers 反向代理 OSS 图片
  • 自定义 Referer 防盗链
  • 将国外 API（如 OpenAI）代理到 Workers，解决网络访问问题
  • URL 短链接服务
  • 构建类似 ChatGPT 的 AI 对话平台
  • RAG + Vectorize 知识库检索

Workers 都可以作为统一的边缘入口，将请求处理、鉴权、缓存和 AI 调用集中在一起，实现低延迟、免运维且易于全球部署的架构。