Cloudflare Workers 与 Pages
这页适合作为“Cloudflare 边缘应用的总入口”。最容易混淆的地方通常不是命令怎么写，而是：什么时候该用 Workers，什么时候该用 Pages，以及 KV / D1 / R2 分别适合承载什么。
先按场景选
- 纯静态站点或前端项目：优先 Pages
- 边缘 API、鉴权、中间层逻辑：优先 Workers
- 简单配置、缓存、轻量键值数据：优先 KV
- 轻量关系型数据、边缘查询：优先 D1
- 文件、图片、附件、归档对象：优先 R2
如果你的项目既有前端又有轻量 API，常见做法是 Pages 托管站点，Workers / Functions 承担边缘逻辑。
Wrangler CLI
# 安装
npm install -g wrangler
# 登录
wrangler login
# 查看账户信息
wrangler whoami
推荐上手顺序
建议按这个顺序推进：
- 先把
wrangler登录和本地调试跑通 - 再写一个最小 Worker 或静态站点
- 再补环境变量和 Secret
- 再接 KV / D1 / R2 中真正需要的一项
- 最后再做生产域名、监控、定时任务和多环境配置
先把一条最小链路打通，比一开始把所有 Cloudflare 服务都接上更稳。
Workers 开发
创建项目
wrangler init my-worker
基本示例
// src/index.ts
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
if (url.pathname === "/api/hello") {
return Response.json({ message: "Hello World" });
}
return new Response("Not Found", { status: 404 });
},
};
本地开发
wrangler dev
部署
wrangler deploy
Pages 部署
从 CLI 部署
# 部署静态站点
wrangler pages deploy ./dist --project-name=my-site
# 部署 Nuxt 项目
npm run build
wrangler pages deploy ./dist
wrangler.jsonc 配置
{
"name": "my-site",
"pages_build_output_dir": "./dist",
"compatibility_date": "2025-01-01",
}
KV 存储
键值存储，适合配置、缓存等场景。
# 创建命名空间
wrangler kv namespace create MY_KV
# 写入
wrangler kv key put --namespace-id=xxx "key" "value"
# 读取
wrangler kv key get --namespace-id=xxx "key"
在 Worker 中使用：
export default {
async fetch(request: Request, env: Env) {
// 读取
const value = await env.MY_KV.get("key");
// 写入（可设置过期时间）
await env.MY_KV.put("key", "value", { expirationTtl: 3600 });
return Response.json({ value });
},
};
D1 数据库
边缘 SQLite 数据库。
# 创建数据库
wrangler d1 create my-db
# 执行 SQL
wrangler d1 execute my-db --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
# 从文件执行
wrangler d1 execute my-db --file schema.sql
在 Worker 中使用：
export default {
async fetch(request: Request, env: Env) {
const { results } = await env.DB.prepare("SELECT * FROM users WHERE id = ?")
.bind(1)
.all();
return Response.json(results);
},
};
R2 对象存储
S3 兼容的对象存储，无出口费用。
# 创建 Bucket
wrangler r2 bucket create my-bucket
在 Worker 中使用：
export default {
async fetch(request: Request, env: Env) {
// 上传
await env.MY_BUCKET.put("file.txt", "Hello World");
// 下载
const object = await env.MY_BUCKET.get("file.txt");
return new Response(object?.body);
},
};
环境变量与 Secrets
# 设置 Secret
wrangler secret put API_KEY
# 在 wrangler.jsonc 中配置普通变量
{
"vars": {
"ENVIRONMENT": "production",
},
}
常见问题
本地能跑，部署后报绑定不存在
通常说明：
wrangler配置里没声明绑定- 生产环境和本地环境的变量 / Secret 没同步
- Pages / Workers 读的不是同一套配置
KV / D1 / R2 到底怎么选
一个简单判断方式：
- 只按 key 读写：KV
- 需要 SQL 结构和关系查询：D1
- 存文件和二进制对象：R2
为什么 Workers 很快，但业务还是不稳
边缘函数快不代表整个系统天然稳。真正影响稳定性的往往是：
- 外部 API 延迟
- 数据存储选择不合适
- 环境变量和密钥管理混乱
- 监控和日志没有补齐
风险提醒
- 不要把 Secret 放进公开变量
- Pages 和 Workers 的环境配置要明确区分
- 上 D1 / KV / R2 前先确认访问模式，避免先选错存储再返工
延伸阅读
参考链接
- Cloudflare Workers 文档 — 官方文档
- Cloudflare Pages 文档 — 部署指南
- D1 文档 — 数据库
- R2 文档 — 对象存储
- Wrangler GitHub — CLI 源码