如何使用Cloudflare部署后端

在 AI 产品出海的旅程中，后端基础设施的选择直接影响产品的全球响应速度和运营成本。传统的云服务器方案需要你在全球各地部署节点、管理服务器、处理证书和扩展性问题。Cloudflare Workers 提供了一种截然不同的思路——将代码部署到全球 300 多个边缘节点，无需管理服务器，按实际计算资源付费。对于 AI 产品的轻量级 API 服务、代理层、鉴权中间件和数据处理管道而言，Workers 是当前最具性价比的部署选项之一。

本文将从零开始，系统介绍如何使用 Cloudflare Workers 部署后端服务，覆盖 Workers 的核心概念、部署流程、存储方案、自定义域名配置、环境变量管理以及常见问题处理。

Cloudflare Workers 是什么

边缘计算与 Serverless 的结合

Cloudflare Workers 是一个运行在 Cloudflare 全球边缘网络上的 Serverless 执行环境。它基于 V8 Isolates 技术——与 Chrome 浏览器中运行 JavaScript 的引擎相同。每个 Worker 运行在独立的隔离环境中，启动时间通常在 5 毫秒以内，没有传统 Serverless 平台的冷启动延迟。

与传统云服务器的区别在于：你不再租用某一台机器，而是将代码分发到 Cloudflare 在全球 300 多个城市的边缘节点上。当用户发起请求时，离用户最近的节点处理请求并返回响应。这意味着一个部署在 Cloudflare 上的 API，无论用户来自东京、柏林还是圣保罗，响应延迟都控制在个位数毫秒级别。

核心特性

Workers 的吸引力来自几个方面：

• 零冷启动：V8 Isolates 不需要加载操作系统或运行时环境，请求到达即可执行
• 按 CPU 时间计费：不按请求次数或运行时长收费，只为实际计算消耗的资源付费
• 无限并发：平台自动处理扩展，不需要配置实例数量或自动伸缩策略
• 原生 Web API：使用标准的 Request/Response API，与 Web 标准完全兼容
• Node.js 兼容性：通过 nodejs_compat 标志，可以运行大多数 Node.js 库

Workers 与传统服务器的定位差异

部署流程：从创建到上线

第一步：安装 Wrangler CLI

Wrangler 是 Cloudflare 官方的 Workers 命令行工具，负责项目的创建、配置、本地调试和部署。

npm install -g wrangler

安装完成后，登录 Cloudflare 账户：

wrangler login

这条命令会打开浏览器，引导你完成 OAuth 授权。授权成功后，Wrangler 会在本地保存认证凭据。

第二步：创建项目

使用 Cloudflare 的 create-cloudflare 脚手架工具（简称 C3）初始化项目：

npm create cloudflare@latest my-backend

C3 会引导你选择项目模板。对于后端服务，推荐选择「Hello World example」或「Worker only」模板。选择 TypeScript 作为开发语言，项目结构会自动生成。

进入项目目录：

cd my-backend

第三步：配置 wrangler.toml

wrangler.toml 是项目的核心配置文件，定义了 Worker 的名称、入口文件、兼容性日期以及绑定的资源。

一个典型的后端服务配置如下：

name = "my-backend"
main = "src/index.ts"
compatibility_date = "2026-06-01"
compatibility_flags = ["nodejs_compat"]
 
# 绑定 KV 命名空间
[[kv_namespaces]]
binding = "CACHE"
id = "<your-kv-namespace-id>"
 
# 绑定 D1 数据库
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "<your-d1-database-id>"
 
# 绑定 R2 存储桶
[[r2_buckets]]
binding = "STORAGE"
bucket_name = "my-assets"

几点说明：

• compatibility_date 决定了 Worker 运行时的行为模式，保持更新可以获得最新的 API 支持和 Bug 修复
• compatibility_flags 中的 nodejs_compat 启用 Node.js 内置模块支持，使用 Express、Hono 等框架时必须开启
• 各种 binding 是将 Cloudflare 资源（KV、D1、R2 等）注入到 Worker 运行环境中，代码通过 env.CACHE、env.DB 等方式访问

第四步：编写业务代码

一个基本的 API 服务入口文件：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url)
 
    if (url.pathname === '/api/health') {
      return Response.json({ status: 'ok', timestamp: Date.now() })
    }
 
    if (url.pathname === '/api/data' && request.method === 'GET') {
      // 从 KV 读取缓存
      const cached = await env.CACHE.get('data-key')
      if (cached) {
        return new Response(cached, {
          headers: { 'Content-Type': 'application/json', 'X-Cache': 'HIT' },
        })
      }
 
      // 从 D1 查询数据库
      const result = await env.DB.prepare('SELECT * FROM items LIMIT 10').all()
 
      // 写入缓存，TTL 60 秒
      await env.CACHE.put('data-key', JSON.stringify(result), { expirationTtl: 60 })
 
      return Response.json(result, {
        headers: { 'Content-Type': 'application/json', 'X-Cache': 'MISS' },
      })
    }
 
    return new Response('Not Found', { status: 404 })
  },
}

这段代码展示了 Workers 的基本模式：通过 fetch 处理请求，通过 env 访问绑定的资源。

第五步：本地调试

Wrangler 提供了本地开发服务器，支持热重载：

wrangler dev

本地启动后，默认监听 http://localhost:8787。修改代码后自动重新加载，无需手动重启。

本地开发时的环境变量和 Secrets 放在项目根目录的 .dev.vars 文件中：

API_KEY=your-local-api-key
DATABASE_URL=your-local-db-url

第六步：部署

wrangler deploy

部署完成后，Wrangler 会输出 Worker 的访问地址，格式通常为 https://my-backend.<your-account>.workers.dev。

如果配置了 CI/CD 流水线，也可以在 GitHub Actions 中自动部署：

- name: Deploy Worker
  run: npx wrangler deploy
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

存储选项：KV、D1 与 R2

Workers 本身是无状态的计算环境，数据持久化需要搭配 Cloudflare 的存储产品。三者定位不同，解决不同场景的问题。

Workers KV：全球分布的键值存储

KV 是一个最终一致的键值数据库，数据会自动复制到全球所有边缘节点。它的核心优势是读取速度极快——无论请求来自哪个节点，都能在 10 毫秒以内返回结果。

但 KV 的写入有速率限制：每个 key 每秒最多 1 次写入，写入后需要约 60 秒才能在全球所有节点生效。这意味着 KV 不适合频繁更新的数据，但非常适合读多写少的场景。

典型用途：会话缓存、配置信息、API 凭证存储、功能开关（feature flags）。

// 写入 KV，设置 300 秒过期
await env.CACHE.put('session:abc123', JSON.stringify(sessionData), {
  expirationTtl: 300,
})
 
// 读取 KV
const session = await env.CACHE.get('session:abc123', 'json')

D1：原生 Serverless SQL 数据库

D1 是基于 SQLite 构建的托管关系型数据库。它支持标准的 SQL 查询、事务、外键约束，适合需要复杂查询和强一致性的场景。

D1 的单库容量上限为 10 GB。如果你的数据量超过这个限制，需要设计分库策略。D1 的写入是强一致的，读取可以通过 Read Replica 分担负载。

典型用途：用户资料、订单记录、产品目录、需要 JOIN 查询的关系型数据。

// 创建数据库
// wrangler d1 create my-database
 
// 在 wrangler.toml 中绑定
// [[d1_databases]]
// binding = "DB"
// database_name = "my-database"
// database_id = "<database-id>"
 
// 查询
const users = await env.DB.prepare(
  'SELECT id, name, email FROM users WHERE status = ? LIMIT ?'
)
  .bind('active', 20)
  .all()
 
// 写入（支持事务）
await env.DB.batch([
  env.DB.prepare('INSERT INTO orders (user_id, total) VALUES (?, ?)').bind(userId, total),
  env.DB.prepare('UPDATE users SET order_count = order_count + 1 WHERE id = ?').bind(userId),
])
 
// 远程执行 SQL 文件
// wrangler d1 execute my-database --remote --file=./schema.sql

R2：S3 兼容的对象存储

R2 是大文件和非结构化数据的存储方案。它与 AWS S3 API 兼容，单文件最大支持 5 TB，且出站流量完全免费——这在 Cloudflare 之前是对象存储领域最大的成本项之一。

典型用途：用户上传的图片和视频、机器学习模型文件、日志归档、静态资源。

// 上传文件到 R2
await env.STORAGE.put('uploads/avatar-123.png', request.body, {
  httpMetadata: { contentType: 'image/png' },
})
 
// 从 R2 读取
const object = await env.STORAGE.get('uploads/avatar-123.png')
if (object) {
  return new Response(object.body, {
    headers: { 'Content-Type': 'image/png', 'Content-Length': String(object.size) },
  })
}

存储选项对比

在实际项目中，这三种存储经常组合使用。一个典型的 AI 产品后端架构可能是：KV 存储用户会话和功能开关，D1 管理用户账户和订阅信息，R2 保存用户上传的素材和生成的图片。

自定义域名配置

部署完成后，Workers 默认使用 https://<worker-name>.<subdomain>.workers.dev 的域名。生产环境中，你需要使用自定义域名来提升品牌形象和可信度。

前置条件

• 域名已添加到 Cloudflare 账户（即 DNS 由 Cloudflare 管理）
• 域名已验证且状态为 Active

在 wrangler.toml 中配置

# 方式一：通过 routes 配置
[[routes]]
pattern = "api.example.com"
custom_domain = true
 
# 方式二：直接指定 custom_domain（较新的语法）
# custom_domain = "api.example.com"

在 Dashboard 中配置

也可以通过 Cloudflare Dashboard 操作：

1. 进入 Workers & Pages → 选择你的 Worker
2. 点击「Settings」→「Domains & Routes」
3. 点击「Add」→ 选择「Custom Domain」
4. 输入域名（如 api.example.com），确认

Cloudflare 会自动处理 DNS 记录创建和 SSL 证书签发，不需要手动配置 CNAME 或申请证书。

子路径路由

如果你希望将同一个域名的不同路径路由到不同的 Worker，可以使用 routes 配置：

[[routes]]
pattern = "example.com/api/*"
zone_name = "example.com"
 
[[routes]]
pattern = "example.com/webhook/*"
zone_name = "example.com"

需要注意的是，官方推荐生产环境的 Worker 使用自定义域名而非 workers.dev 子域名，原因包括更好的 SEO 表现、更灵活的 SSL 配置以及与现有基础设施的一致性。

环境变量和 Secrets

普通环境变量

在 wrangler.toml 中定义：

[vars]
ENVIRONMENT = "production"
API_VERSION = "v1"
ALLOWED_ORIGINS = "https://example.com,https://app.example.com"

在代码中通过 env.ENVIRONMENT 访问。

Secrets（加密变量）

Secrets 是一种特殊的环境变量，其值在设置后不会在 Dashboard 或 Wrangler 中显示。用于存储 API 密钥、数据库密码、OAuth 凭证等敏感信息。

# 设置 Secret
wrangler secret put API_SECRET_KEY
 
# 系统会提示你输入值，输入后自动加密存储

在代码中，Secrets 的访问方式与普通环境变量完全一致：

const apiKey = env.API_SECRET_KEY

多环境管理

Wrangler 支持按环境（preview/production）区分配置：

[env.staging]
name = "my-backend-staging"
 
[env.staging.vars]
ENVIRONMENT = "staging"
 
[env.production]
name = "my-backend"
 
[env.production.vars]
ENVIRONMENT = "production"

部署到指定环境：

wrangler deploy --env staging
wrangler deploy --env production

本地开发时，在 .dev.vars 文件中设置本地专用的环境变量和 Secrets，这个文件应该加入 .gitignore。

常见问题处理

1. 请求超时

Workers 对单个请求的执行时间有上限。免费版限制为 10 秒 CPU 时间，付费版为 30 秒。如果你的请求涉及外部 API 调用或数据库查询，需要注意控制响应时间。

解决方案：对于长时间运行的任务，使用 ctx.waitUntil() 将非关键逻辑放到后台执行，先返回响应给客户端。更耗时的任务可以交给 Cloudflare Queues 或 Workflows 异步处理。

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // 立即返回响应
    const response = Response.json({ accepted: true })
 
    // 后台处理耗时任务
    ctx.waitUntil(
      env.QUEUE.send({ taskId: 'process-data', payload: await request.json() })
    )
 
    return response
  },
}

2. 内存限制

每个 Worker 实例的内存上限为 128 MB。处理大文件或大量数据时，务必使用流（Stream）而非一次性加载到内存。

// 错误做法：将整个文件加载到内存
const data = await request.arrayBuffer()
 
// 正确做法：使用流式处理
const reader = request.body!.getReader()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  // 逐块处理 value
}

3. 全局变量陷阱

Workers 的隔离环境会在多次请求之间复用。这意味着全局变量的状态不会在请求之间重置——如果你在请求 A 中修改了一个全局变量，请求 B 可能看到被修改后的值。

// 危险：全局变量会在请求之间保持状态
let requestCount = 0
 
export default {
  async fetch() {
    requestCount++ // 这不是线程安全的
    return new Response(`Count: ${requestCount}`)
  },
}

解决方案：将请求相关的状态通过函数参数传递，而不是依赖全局变量。

4. CORS 跨域问题

API 服务经常需要处理浏览器的跨域请求。需要正确设置 CORS 头：

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}
 
export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method === 'OPTIONS') {
      return new Response(null, { headers: corsHeaders })
    }
    // 处理业务逻辑...
    return new Response(JSON.stringify(data), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
    })
  },
}

5. D1 数据库连接问题

D1 不是传统的连接池数据库，而是通过 Bindings 直接调用。你不需要管理连接字符串或连接池——Workers 运行时自动处理底层连接。如果你需要从 Workers 连接外部数据库（如 PostgreSQL、MySQL），使用 Hyperdrive 可以获得区域连接池的优势。

实践案例

案例一：AI 图片生成 API 的代理层

一个 AI 产品需要将图片生成请求转发到后端模型服务，同时做鉴权、限流和结果缓存。

架构设计：

• Workers 作为 API 网关，处理请求鉴权和限流
• KV 缓存已生成的图片 URL，避免重复调用模型服务
• R2 存储生成的图片文件
• D1 记录用户的调用次数和配额

工作流程：用户请求到达 Workers → 检查 D1 中的配额 → 检查 KV 中是否有缓存 → 如果有缓存直接返回，如果没有则调用模型服务 → 将结果存入 R2 并更新 KV → 扣减 D1 中的配额 → 返回结果。

这种架构的优势在于全球低延迟、按实际计算量计费、无需管理服务器。图片缓存命中时，响应时间在 10 毫秒以内。

案例二：多租户 SaaS 后端的边缘部署

一个面向海外客户的 SaaS 产品需要处理多租户的数据隔离、Webhook 接收和通知推送。

架构设计：

• Workers 处理所有 API 请求，根据请求头中的租户标识路由到不同的数据空间
• D1 为每个租户维护独立的数据视图（通过 tenant_id 字段隔离）
• R2 存储各租户上传的文档和素材
• KV 存储租户级别的配置和功能开关
• Cloudflare Queues 异步处理通知推送和邮件发送

关键设计决策：

• 使用 D1 而非多个独立数据库，通过 tenant_id 做逻辑隔离，降低管理复杂度
• KV 中的 key 以 tenant:{tenant_id}:config 的格式命名，避免不同租户的数据混淆
• Webhook 接收使用 ctx.waitUntil() 异步处理，先返回 200 给调用方，避免超时

这套架构支撑了日均 50 万次 API 调用，全球 P95 延迟低于 100 毫秒，月基础设施成本不到 50 美元。

部署流程全景

部署前检查清单

在将 Worker 部署到生产环境之前，逐项确认以下内容：

• compatibility_date 设置为最近的日期，确保使用最新的运行时特性
• nodejs_compat 已启用（如果使用 Node.js 框架或库）
• 所有 Secrets 通过 wrangler secret put 设置，而非硬编码在代码中
• .dev.vars 文件已加入 .gitignore，避免本地凭据泄露
• 存储资源的 Bindings（KV、D1、R2）已在 wrangler.toml 中正确配置
• 远程数据库的 Schema 已通过 wrangler d1 execute --remote 初始化
• CORS 头已正确配置，允许前端域名的跨域请求
• 错误处理覆盖所有异常路径，不会返回裸露的错误堆栈
• 自定义域名已配置并验证 SSL 证书状态为 Active
• 生产环境的日志和告警已配置，推荐使用结构化 JSON 日志
• 关键请求路径已做性能测试，确认延迟和吞吐量满足预期
• CI/CD 流水线已配置，支持自动化部署和回滚

平台对比：Workers 与其他部署选项

对于 AI 产品出海的后端部署，以下是几个主流方案的横向对比：

总结

Cloudflare Workers 为 AI 产品出海提供了一个轻量、高效且成本可控的后端部署方案。它的核心价值在于：全球边缘分布带来的低延迟、Serverless 架构带来的零运维、以及按 CPU 时间计费带来的成本优化。

对于大多数 AI 产品的早期阶段，Workers + KV + D1 + R2 的组合足以支撑完整的后端需求：API 服务、数据存储、文件管理和缓存。当产品规模增长、出现长连接或计算密集型需求时，可以将 Workers 作为边缘网关，将重计算任务交给专门的推理服务，形成分层架构。

关键决策点在于：如果你的服务以 API 请求为主、需要全球低延迟、且不需要长时间运行的进程，Workers 是理想选择。如果你需要 WebSocket 长连接、GPU 计算或完全控制运行时环境，则需要考虑 Workers 与其他服务的组合方案。

参考资料

1. Cloudflare Workers 官方文档 — Workers 平台的完整文档，包含快速开始、API 参考和最佳实践
2. 选择数据存储产品 — 官方存储方案选型指南，详细对比 KV、D1、R2 和 Durable Objects
3. Workers 最佳实践 — 官方最佳实践指南，覆盖配置、性能、安全和可观测性
4. Architecting on Cloudflare: Choosing the Right Storage — 深入分析 KV、D1、R2 和 Durable Objects 的选型决策框架
5. 部署 Express.js 应用到 Workers — 官方教程，演示如何在 Workers 上运行 Express 后端
6. Cloudflare Workers 定价 — 最新的定价信息，包含免费套餐和付费套餐的详细对比
7. Wrangler 配置参考 — wrangler.toml 的完整配置项说明
8. Cloudflare 环境变量与 Secrets — 环境变量和 Secrets 的管理方式