Cloudflare Worker 教程: 从入门到精通 – wiki基地

作者： /

Cloudflare Worker 教程：从入门到精通

Cloudflare Worker 教程：从入门到精通

引言

在当今高速发展的互联网世界中，用户对应用响应速度的要求越来越高。传统中心化服务器的模式已逐渐难以满足这种需求，而边缘计算的兴起为我们带来了新的解决方案。Cloudflare Workers 作为领先的无服务器边缘计算平台，允许开发者将代码部署在全球各地离用户最近的数据中心，从而实现极低的延迟和卓越的性能。

本教程旨在为所有对 Cloudflare Workers 感兴趣的开发者提供一个从零开始到精通的全面指南。无论您是初次接触无服务器技术，还是希望将现有应用迁移到边缘，本文都将为您提供所需的知识和实践步骤。

一、Cloudflare Workers 简介

1. 什么是 Cloudflare Workers？

Cloudflare Workers 是一个无服务器（Serverless）计算平台，它允许开发者在 Cloudflare 遍布全球的边缘网络上运行 JavaScript、TypeScript、Python（通过 Pyodide）甚至编译为 WebAssembly 的 Rust 代码。与传统服务器不同，您的代码运行在 V8 引擎（与 Chrome 浏览器相同的 JavaScript 引擎）的隔离环境中，无需管理任何服务器基础设施。当请求到达时，Worker 会在离用户最近的边缘位置执行，极大地缩短了响应时间。

2. 核心优势

  • 低延迟 (Low Latency)：代码在靠近用户的 Cloudflare 全球数据中心运行，显著减少了请求和响应的物理距离，通常可在 50 毫秒内响应。
  • 自动扩容 (Automatic Scaling)：平台自动处理流量峰值和低谷，无需手动配置或担心服务器过载，确保应用始终可用。
  • 无冷启动 (No Cold Starts)：与许多其他无服务器函数不同，Cloudflare Workers 始终处于“热”状态，这意味着请求能够即时响应，避免了传统无服务器函数常见的冷启动延迟。
  • 成本效益 (Cost-Effectiveness)：采用按需付费模式，您只需为实际使用的计算资源付费，大大降低了运维成本。
  • 安全性 (Security)：您的 Worker 部署在 Cloudflare 强大的全球网络之上，天然受益于其 DDoS 防护、WAF 等安全服务，为应用提供额外的保护层。
  • 高性能网络：利用 Cloudflare 优化过的网络基础设施，请求和响应传输更快速、更稳定。

3. 主要应用场景

Cloudflare Workers 的灵活性使其适用于广泛的应用场景：

  • 构建 API 网关和微服务：快速部署和管理轻量级后端 API，实现业务逻辑的分离。
  • 动态路由和重定向：根据用户地理位置、设备类型、请求头等条件智能地路由请求，实现个性化体验或 A/B 测试。
  • 内容修改和 A/B 测试：在边缘修改 HTTP 请求和响应，例如插入广告、修改页面内容、实现国际化或进行 A/B 测试。
  • 数据处理和验证：在请求到达源服务器之前进行数据清洗、格式转换、输入验证或权限检查。
  • 缓存策略：实现自定义缓存逻辑，例如基于请求头或响应内容进行缓存，进一步提升性能并减轻源服务器压力。
  • 全栈应用：结合 Cloudflare 的 KV 存储、D1 数据库和 R2 对象存储，以及 Workers Sites，可以构建完整的全栈无服务器应用。

二、入门：环境搭建与第一个 Worker

1. 先决条件

在开始之前，请确保您的开发环境满足以下条件：

  • Cloudflare 账号：如果您还没有，请访问 Cloudflare 官网 注册一个免费账号。
  • Node.js：安装最新版本的 Node.js (推荐 v20 或更高版本)，其中包含了 npm (Node Package Manager)。您可以从 Node.js 官网 下载。

2. 安装 Wrangler CLI

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

打开您的终端或命令行工具，运行以下命令全局安装 Wrangler：

bash
npm install -g wrangler

安装完成后，您可以通过运行 wrangler --version 来验证安装是否成功。

接下来，您需要登录您的 Cloudflare 账号以授权 Wrangler。运行以下命令：

bash
wrangler login

该命令会在您的默认浏览器中打开 Cloudflare 登录页面。登录并授权后，Wrangler 将与您的 Cloudflare 账号关联，允许您通过命令行管理 Workers。

3. 创建第一个 Worker 项目

Cloudflare 提供了一个便捷的 CLI 工具 create-cloudflare 来快速创建 Worker 项目。在您希望创建项目的目录下，运行：

bash
npm create cloudflare@latest my-first-worker

系统会提示您进行一系列选择：

  1. Select a template: 选择 “Hello World example”。
  2. Select project type: 选择 “Worker only”。
  3. Select language: 您可以选择 “TypeScript” 或 “JavaScript”。对于初学者，JavaScript 可能更直接，但 TypeScript 提供了更好的类型安全和开发体验。
  4. Do you want to deploy?: 选择 “no”，我们稍后手动部署。

完成这些步骤后，一个名为 my-first-worker 的新项目目录将被创建。

4. 本地开发与测试

进入您新创建的项目目录：

bash
cd my-first-worker

使用 Wrangler 在本地启动开发服务器：

bash
npx wrangler dev

这会在本地启动一个服务器（通常在 http://localhost:8787），并模拟 Cloudflare Workers 的运行环境。您可以在浏览器中访问此地址来测试您的 Worker。wrangler dev 会监听文件变化并自动重新加载，极大地提高了开发效率。

5. 部署到 Cloudflare

当您对本地测试满意后，可以将 Worker 部署到 Cloudflare 的全球网络：

bash
npx wrangler deploy

Wrangler 会将您的代码打包并上传到 Cloudflare。部署成功后，您将获得一个 *.workers.dev 域名（例如 my-first-worker.yourusername.workers.dev），您的 Worker 将在该域名下运行，全球用户即可访问。

6. Worker 代码结构

一个基本的 Worker 通常包含一个 src/index.ts (或 .js) 文件。以下是一个简单的 TypeScript Worker 示例：

“`typescript
// src/index.ts
export interface Env {
// 定义环境变量或绑定，例如 KV 命名空间
// MY_KV: KVNamespace;
}

export default {
// fetch 方法是 Worker 的核心，它处理传入的 HTTP 请求
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {
// 解析请求 URL
const url = new URL(request.url);

// 根据路径返回不同的响应
if (url.pathname === '/hello') {
  return new Response('Hello from Cloudflare Worker!', {
    headers: { 'content-type': 'text/plain' },
  });
}

// 默认响应
return new Response('Welcome to my Worker!', {
  headers: { 'content-type': 'text/plain' },
});

},
};
“`

Worker 的核心是一个实现了 fetch 方法的对象，该方法接收一个 Request 对象并必须返回一个 Response 对象。env 对象包含了通过 wrangler.toml 配置的环境变量和绑定。ctx 对象则提供了执行上下文，例如 waitUntil 方法用于延长 Worker 的生命周期以执行异步任务。

三、核心概念与进阶功能

1. 请求处理与响应

Worker 通过 fetch 事件处理 HTTP 请求。Request 对象包含了请求的所有信息，您需要返回一个 Response 对象。

  • HTTP 方法：通过 request.method 可以获取请求的 HTTP 方法（GET, POST, PUT, DELETE 等），从而实现不同的业务逻辑。
  • URL 和查询参数：使用 new URL(request.url) 可以方便地解析 URL，获取路径、查询参数（url.searchParams）和主机名等信息。
  • 请求头和响应头：通过 request.headers 可以读取请求头，通过 response.headers.set() 或在 new Response() 中设置 headers 选项来添加或修改响应头。
  • 请求体：对于 POST/PUT 等带有请求体的请求，可以使用 request.json() (解析 JSON)、request.text() (解析纯文本)、request.formData() (解析表单数据) 等方法异步读取请求体内容。

2. 绑定 (Bindings)

绑定是 Cloudflare Workers 的一个强大功能，它允许您的 Worker 无缝地与其他 Cloudflare 服务进行交互，而无需在代码中硬编码凭据，确保了安全性和易用性。这些绑定在 wrangler.toml 中配置，并通过 env 对象注入到 Worker 代码中。

  • KV 存储 (Key-Value Storage)：一个高可用、低延迟的键值存储，非常适合存储缓存数据、用户偏好设置、配置信息或短生命周期的会话数据。
    • 在 wrangler.toml 中配置：
      toml
      [[kv_namespaces]]
      binding = "MY_KV" # 对应 env.MY_KV
      id = "YOUR_KV_NAMESPACE_ID" # 在 Cloudflare Dashboard 创建
    • 在 Worker 代码中访问：await env.MY_KV.put('key', 'value'); 和 const value = await env.MY_KV.get('key');
  • D1 数据库 (D1 Database)：Cloudflare 提供的基于 SQLite 的无服务器 SQL 数据库，在边缘运行，支持标准的 SQL 查询，非常适合需要结构化数据存储的应用。
    • 在 wrangler.toml 中配置：
      toml
      [[d1_databases]]
      binding = "DB" # 对应 env.DB
      database_name = "my-database"
      database_id = "YOUR_D1_DATABASE_ID" # 在 Cloudflare Dashboard 创建
    • 在 Worker 代码中访问：const { results } = await env.DB.prepare('SELECT * FROM users').all();
  • R2 对象存储 (R2 Object Storage)：S3 兼容的无服务器对象存储服务，用于存储大量非结构化数据，如图片、视频、文档、日志文件等。R2 的最大优势是不收取出口流量费。
    • 在 wrangler.toml 中配置：
      toml
      [[r2_buckets]]
      binding = "MY_BUCKET" # 对应 env.MY_BUCKET
      bucket_name = "my-static-files"
    • 在 Worker 代码中访问：await env.MY_BUCKET.put('image.png', imageBuffer);
  • Durable Objects (有状态对象)：提供全局唯一的、有状态的单例对象，用于构建实时协作应用、游戏后端、聊天室等需要持久化状态和协调的场景。Durable Objects 可以保证在特定名称下的所有请求都路由到同一个实例。
  • Service Bindings (服务绑定)：允许一个 Worker 安全地调用另一个已部署的 Worker，实现微服务架构，提高代码复用性和模块化。

3. 静态资源托管 (Workers Static Assets)

Cloudflare Workers 结合 Workers Sites 可以轻松托管静态网站或单页应用 (SPA)。您可以将 HTML、CSS、JavaScript 和图片等静态文件与 Worker 代码一起部署。Cloudflare 会自动处理静态文件的缓存和压缩，无需单独的静态文件服务器，极大地简化了部署流程。

4. Node.js 兼容性

Cloudflare Workers 提供了对部分 Node.js API 的兼容层，允许您在 Worker 中使用许多现有的 npm 包，例如 Buffer、Crypto、EventEmitter 等。这大大扩展了 Worker 的功能和生态系统，使得将现有 Node.js 代码迁移到 Workers 变得更加容易。

5. Workers AI

Cloudflare Workers AI 允许您在边缘运行 AI 模型进行推理，例如文本生成、图像识别、嵌入生成等，而无需管理复杂的 GPU 基础设施。这使得在边缘构建智能应用成为可能，同时保持低延迟和高效率。

6. 队列 (Queues)

Cloudflare Queues 提供了一个消息队列服务，用于在 Worker 之间或 Worker 与其他服务之间进行异步通信和后台处理。例如，当用户上传文件后，Worker 可以将处理任务放入队列，由另一个 Worker 在后台异步处理，避免阻塞用户请求。

7. 定时任务 (Scheduled Workers)

您可以配置 Workers 定期运行，执行类似于传统 Cron Job 的任务。这非常适合进行数据清理、生成报告、定期抓取数据或发送定时通知等自动化操作。

四、高级主题

1. 自定义路由与域名

默认情况下，Worker 部署在 *.workers.dev 子域名下。为了提供更专业的形象和更好的用户体验，您可以通过 Cloudflare Dashboard 或在 wrangler.toml 文件中配置自定义域名和路由规则，将 Worker 绑定到您自己的域名下。

wrangler.toml 示例：

“`toml
name = “my-worker”
main = “src/index.ts”
compatibility_date = “2023-01-01”

routes = [
{ pattern = “api.example.com/“, zone_id = “YOUR_ZONE_ID” }, # 将 api.example.com 的请求路由到此 Worker
{ pattern = “www.example.com/api/“, zone_id = “YOUR_ZONE_ID” } # 将 www.example.com/api/* 的请求路由到此 Worker
]
“`

2. CI/CD 自动化部署

为了实现高效的开发流程和持续集成/持续部署 (CI/CD)，您可以将 Worker 的部署集成到自动化管道中，例如使用 GitHub Actions、GitLab CI/CD 或 Jenkins。通过配置 Cloudflare API Token，可以在代码提交、合并或版本发布后自动构建、测试和部署 Worker，确保代码变更能够快速、可靠地推送到生产环境。

3. 错误处理与调试

有效的错误处理和调试对于开发健壮的 Worker 至关重要。

  • console.log()：在 Worker 代码中使用 console.log() 输出调试信息，这些信息可以在 Cloudflare Dashboard 的 Workers 日志中查看。
  • wrangler dev：在本地开发时，wrangler dev 会在终端实时显示详细的日志和错误信息，方便快速定位问题。
  • Cloudflare Dashboard：提供实时的 Workers 日志、请求分析、错误报告和堆栈跟踪，帮助您监控和调试生产环境中的 Worker。
  • try...catch 块：在 Worker 代码中合理使用 try...catch 块来捕获和处理可能发生的运行时错误，并返回友好的错误响应。
  • event.waitUntil()：对于 Worker 的后台任务，如发送日志或更新数据库，应使用 event.waitUntil() 确保这些任务在 Worker 响应返回后也能完成，避免因 Worker 提前结束而导致数据丢失。

4. 性能优化

  • 缓存策略：充分利用 Cloudflare 的强大缓存能力。除了 Cloudflare 提供的 CDN 缓存，您还可以使用 Workers KV 存储或 Cache API 实现自定义的、更细粒度的缓存逻辑，减少对源服务器的请求，降低延迟。
  • 最小化外部 API 调用：尽量在 Worker 内部处理逻辑，减少对外部服务的依赖。如果必须进行外部调用，应考虑异步处理和适当的超时设置。
  • 代码精简：Worker 的执行时间通常很短，因此应保持代码的精简和高效，避免不必要的计算或资源消耗。
  • HTTP/2 和 HTTP/3：Cloudflare Workers 原生支持最新的 HTTP 协议，利用这些协议的优势可以进一步提高性能。
  • 压缩：Worker 默认会压缩响应内容，但您也可以手动控制压缩方式。

5. 安全性

  • HTTP 安全头：在 Worker 中设置 HSTS (Strict-Transport-Security)、CSP (Content-Security-Policy)、X-Frame-Options 等 HTTP 安全头，增强应用安全性，防范 XSS、点击劫持等攻击。
  • 数据验证：在 Worker 接收到请求后，对所有输入数据进行严格的验证和清理，防止 SQL 注入、跨站脚本 (XSS) 和其他常见的 Web 漏洞。
  • 环境变量和秘密：使用 Wrangler 提供的机制管理环境变量和敏感信息（如 API 密钥），避免将它们硬编码到代码中。敏感信息应作为秘密变量存储在 Cloudflare 中，并通过绑定安全地注入到 Worker 中。
  • 权限管理：仔细管理 Worker 访问 Cloudflare 资源的权限，遵循最小权限原则。

6. 测试

编写单元测试和集成测试是确保 Worker 代码质量和稳定性的重要手段。Cloudflare Workers 支持使用 Vitest、Jest 等流行的 JavaScript 测试框架进行测试。create-cloudflare 模板通常会包含 Vitest 的配置，让您能够轻松开始测试。

五、部署与监控

1. 部署流程回顾

  1. 安装 Wrangler CLI：npm install -g wrangler
  2. 登录 Cloudflare：wrangler login
  3. 创建项目：npm create cloudflare@latest my-worker
  4. 本地开发：npx wrangler dev (在 http://localhost:8787 测试)
  5. 部署：npx wrangler deploy (部署到 Cloudflare 全球网络)

2. Cloudflare Dashboard 监控与分析

部署 Worker 后，您可以通过 Cloudflare Dashboard 访问 Workers & Pages 部分，对您的 Worker 进行全面的监控和管理。

  • 查看部署状态：确认 Worker 是否成功部署，以及当前的 Worker 版本。
  • 访问日志：实时查看 Worker 的执行日志（console.log() 输出）、错误信息和请求详情，帮助您诊断问题。
  • 性能分析：获取关键性能指标，如请求量、平均响应时间、CPU 使用时间、错误率等，从而评估 Worker 的运行状况和性能表现。
  • 配置管理：在 Dashboard 中直观地管理 Worker 的路由、环境变量、秘密变量、绑定和其他设置。
  • 版本回滚：当新版本出现问题时，可以快速回滚到之前的稳定版本。

六、实际案例与最佳实践

  • 构建 API 网关：将多个后端服务聚合到一个统一的 API 端点。在 Worker 中进行请求认证、限速、日志记录和请求转发，实现统一的 API 管理。
  • A/B 测试：根据用户特征（如地理位置、Cookie 或用户代理）将流量路由到不同版本的页面或 API，以便进行产品功能或 UI/UX 的实验。
  • 图片优化服务：在边缘动态调整图片大小、格式和质量，以适应不同设备和网络条件，从而提高页面加载速度。
  • 动态路由：根据请求的路径、头信息或查询参数，将请求转发到不同的源服务器或另一个 Worker，实现复杂的路由逻辑。
  • 全栈应用：结合 Workers、D1 数据库和 Workers Static Assets，构建高性能、低延迟的现代全栈应用，前端由 Workers Static Assets 托管，后端 API 和业务逻辑由 Worker 处理，数据存储在 D1。
  • 无服务器认证：在 Worker 中实现用户身份验证和授权逻辑，保护您的后端 API。
  • Webhook 处理器：作为各种服务的 Webhook 接收器，处理传入的事件通知并执行相应的逻辑，例如触发邮件发送、更新数据库或与其他服务集成。

总结

Cloudflare Workers 提供了一个强大、灵活且高效的平台，让开发者能够轻松构建和部署在全球边缘运行的无服务器应用。通过本教程的学习，您应该已经掌握了从环境搭建、代码编写、本地调试到部署和监控的全过程。从基本的 HTTP 请求处理到利用各种绑定构建复杂应用，Workers 的潜力是巨大的。

现在，是时候开始您自己的 Cloudflare Workers 之旅了！不断探索，持续创新，利用边缘计算的强大能力，为您的用户提供极致的应用体验。

滚动至顶部