Cloudflare Workers 初学者指南

简介

如果你希望构建现代 Web 应用程序而无需管理服务器,Cloudflare Workers 提供了一个远超简单无服务器函数的强大解决方案。与传统平台不同,Workers 现在提供了全栈应用程序所需的一切:通过 D1 提供的 SQL 数据库、通过 Hyperdrive 连接现有的 PostgreSQL 或 MySQL、静态资源托管以及广泛的 Node.js 兼容性——所有这些都在边缘运行,靠近你的用户。

本 Cloudflare Workers 教程涵盖了入门所需的基本概念和工具,从理解基于边缘的执行到构建具有现代数据库连接和资源管理的完整应用程序。

什么是 Cloudflare Workers?

基于边缘的执行解析

Cloudflare Workers 是运行在 Cloudflare 全球数据中心网络上的 JavaScript、TypeScript、Python 或 Rust 函数。你的代码不是在单个服务器上执行,而是在距离每个用户最近的边缘位置运行,通常在地球上任何人的 50 毫秒范围内。

这种基于边缘的模型意味着你的应用程序响应更快,因为请求不需要传输到中央服务器。该平台自动处理扩展——无论你有十个用户还是一千万用户,Workers 都能自动调整而无需配置。

核心概念:绑定和环境

Workers 使用**绑定(bindings)**将你的代码连接到资源。这些不是传统的环境变量,而是与服务的直接连接:

• KV 命名空间用于键值存储
• D1 数据库用于 SQL 操作
• R2 存储桶用于对象存储
• 服务绑定连接到其他 Workers
• Hyperdrive 连接连接到外部数据库

每个绑定作为传递给 Worker 的 env 对象上的属性出现:

export default {
  async fetch(request, env, ctx) {
    // 访问 D1 数据库
    const result = await env.DB.prepare('SELECT * FROM users').all()
    return Response.json(result)
  }
}

使用 Cloudflare D1 数据库的现代数据库选项

D1:边缘上的生产就绪 SQL

Cloudflare D1 数据库将 SQLite 带到边缘,具有自动复制和备份功能。与传统的无服务器数据库不同,D1 在与 Workers 相同的位置运行,消除了数据库查询的网络延迟。

创建 D1 数据库非常简单:

npx wrangler d1 create my-database
npx wrangler d1 execute my-database --file=./schema.sql

你的 Worker 通过绑定访问 D1,使查询感觉像本地操作:

const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
  .bind(userId)
  .first()

Hyperdrive 连接现有数据库

Hyperdrive 连接解决了一个常见挑战:将 Workers 连接到现有的 PostgreSQL 或 MySQL 数据库,包括私有网络中的数据库。Hyperdrive 在 Cloudflare 边缘维护连接池,将连接开销减少多达 30 倍。

设置 Hyperdrive 只需最少的配置:

npx wrangler hyperdrive create my-postgres \
  --connection-string="postgresql://user:pass@host:5432/db"

然后,你的 Worker 使用熟悉的数据库库和 Hyperdrive 连接:

import { Client } from 'pg'

export default {
  async fetch(request, env) {
    const client = new Client(env.HYPERDRIVE.connectionString)
    await client.connect()
    const result = await client.query('SELECT * FROM products')
    return Response.json(result.rows)
  }
}

构建全栈应用程序

Workers 静态资源和路由

Workers 静态资源消除了单独托管的需求。你的 HTML、CSS、JavaScript 和图像与 API 代码一起部署。该平台自动提供带有适当缓存头和压缩的静态文件。

静态资源处理需要在 wrangler.toml 中添加指向公共目录的 assets 条目。

全栈 Worker 的项目结构:

my-app/
├── src/
│   └── index.js        # Worker 代码
├── public/
│   ├── index.html      # 静态资源
│   ├── style.css
│   └── app.js
└── wrangler.toml       # 配置文件

路由处理静态和动态请求:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    
    if (url.pathname.startsWith('/api/')) {
      // 处理 API 路由
      return handleAPI(request, env)
    }
    
    // 提供静态资源
    return env.ASSETS.fetch(request)
  }
}

Node.js 兼容层的优势

Node.js 兼容层使数千个 npm 包能够在 Workers 中工作。与仅支持 Web 标准 API 的早期版本不同,Workers 现在支持 Node.js 内置模块,如 Buffer、crypto、stream 和 path。

在 wrangler.toml 中启用 Node.js 兼容性:

compatibility_flags = ["nodejs_compat"]

这种兼容性意味着现有的 Node.js 代码通常只需最少的更改即可工作,使从传统服务器迁移变得简单。

本地开发工作流

设置你的环境

从 Wrangler 开始,这是 Cloudflare 的 CLI 工具:

npm create cloudflare@latest my-app
cd my-app
npm run dev

Wrangler 提供热重载开发,可在本地访问所有绑定。你的 D1 数据库、KV 命名空间甚至 Hyperdrive 连接都可以在开发模式下工作。

测试和部署

本地开发服务器模拟生产行为:

# 使用本地 D1 数据库进行测试
npx wrangler d1 execute DB --local --file=./seed.sql

# 部署到生产环境
npm run deploy

其他平台功能

虽然本教程专注于核心概念,但 Workers 还提供了值得探索的其他功能:

• **队列(Queues)**用于后台作业处理
• R2 事件通知用于对象存储触发器
• **渐进式部署(Gradual Deployments)**用于安全发布
• Workers 分析和结构化日志记录用于可观测性

这些功能随着应用程序的增长无缝集成。

结论

Cloudflare Workers 已从简单的边缘函数发展为现代 Web 应用程序的完整平台。通过 D1 提供无服务器 SQL,通过 Hyperdrive 连接现有数据库,内置静态资源托管以及全面的 Node.js 兼容性,你可以构建在全球范围内运行且配置最少的全栈应用程序。

从一个简单的 Worker 开始,添加 D1 数据库以实现数据持久化,并根据需要逐步整合 Hyperdrive 或 R2 等功能。该平台处理全球分发的复杂性,让你专注于构建应用程序。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.