Cloudflare Workers入门指南：从零到部署 – wiki词典

作者： /

Cloudflare Workers 入门指南：从零到部署

Cloudflare Workers 提供了一个强大的无服务器执行环境，让开发者能够在 Cloudflare 的全球网络边缘部署 JavaScript、TypeScript 或 WebAssembly 代码。这意味着您的代码将在离用户最近的数据中心运行，从而显著降低延迟并提高应用程序性能。

本指南将带您从零开始，逐步了解如何创建、开发、测试和部署您的第一个 Cloudflare Worker。

1. 引言

什么是 Cloudflare Workers？

Cloudflare Workers 是一个基于 Google V8 引擎构建的无服务器平台，允许您在 Cloudflare 的全球边缘网络上运行代码。您的代码不是在单个服务器上执行，而是在距离每个用户最近的边缘位置运行，通常在地球上任何人的 50 毫秒范围内。

优势

  • 全球部署，低延迟：代码在全球 200 多个数据中心同时运行，确保极低的延迟和快速响应。
  • 无冷启动：Workers 始终处于“热”状态，随时可以响应请求，避免了传统无服务器函数常见的冷启动问题。
  • 按使用付费：您只需为您使用的资源付费，无需管理或扩展服务器。
  • 零维护：Cloudflare 负责底层基础设施的维护和扩展。

2. 准备工作

在开始之前，您需要准备以下事项：

  • Cloudflare 账户：如果您还没有，请前往 Cloudflare 官网注册一个账户。
  • Node.js 和 npm：Wrangler CLI（Cloudflare Workers 的命令行工具）需要 Node.js 和 npm（或 yarn/pnpm）来运行。请确保您的系统已安装 Node.js 16.17.0 或更高版本。

3. 安装 Wrangler CLI

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

全局安装

打开您的终端并运行以下命令来全局安装 Wrangler：
bash
npm install -g @cloudflare/wrangler
或者，您也可以使用 create-cloudflare 工具来初始化项目，它会自动处理 Wrangler 的安装。

登录 Cloudflare

安装完成后，您需要登录您的 Cloudflare 账户，以便 Wrangler 可以代表您管理 Workers。
bash
wrangler login
运行此命令后，您的浏览器将自动打开一个 Cloudflare 登录页面。登录并授权 Wrangler 后，终端会显示配置成功的消息。

4. 创建第一个 Worker 项目

现在，让我们使用 create-cloudflare 工具来创建一个新的 Worker 项目。

bash
npm create cloudflare@latest my-first-worker
此命令将引导您完成项目设置。您可以选择以下选项：
* What would you like to start with? (您想从什么开始？): 选择 Hello World example。
* Which template would you like to use? (您想使用哪个模板？): 选择 Worker only。
* Which language do you want to use? (您想使用哪种语言？): 选择 JavaScript 或 TypeScript。
* Do you want to use git for version control? (您想使用 Git 进行版本控制吗？): 选择 Yes。
* Do you want to deploy your application? (您想部署您的应用程序吗？): 选择 No (我们将在稍后手动部署)。

完成设置后，进入新创建的项目目录：
bash
cd my-first-worker

项目结构

您的项目目录将包含以下主要文件：
* src/index.js (或 src/index.ts)：这是您的 Worker 代码的入口文件。
* wrangler.toml：这是 Wrangler 的配置文件，用于定义 Worker 的名称、路由、绑定等。

5. 编写 Worker 代码

打开 src/index.js (或 src/index.ts) 文件。您会看到一个基本的 “Hello World” 示例。

javascript
// src/index.js
export default {
async fetch(request, env, ctx) {
return new Response('Hello World from Cloudflare Workers!');
},
};

理解 fetch 事件

Cloudflare Workers 遵循 Service Worker API 标准。核心逻辑通常在 fetch 事件监听器中实现。当 Worker 接收到 HTTP 请求时，fetch 事件会被触发。

  • request：表示传入的 HTTP 请求对象。
  • env：一个对象，包含您在 wrangler.toml 中配置的所有绑定（如 KV 命名空间、环境变量等）。
  • ctx：一个对象，提供对 Worker 运行时上下文的访问，例如 waitUntil 方法，用于在响应发送后执行异步任务。

在上面的示例中，Worker 简单地返回一个包含 “Hello World from Cloudflare Workers!” 文本的响应。

6. 本地开发与测试

在部署之前，您可以在本地环境中测试您的 Worker。Wrangler 提供了 wrangler dev 命令，它会在本地启动一个服务器来模拟 Cloudflare Workers 环境。

在项目根目录中运行：
bash
wrangler dev
Wrangler 会在 localhost:8787 启动一个开发服务器。打开浏览器访问 http://localhost:8787/，您应该会看到 “Hello World from Cloudflare Workers!”。在您修改代码并保存后，wrangler dev 会自动重新加载 Worker，您只需刷新浏览器即可看到更改。

7. 配置 wrangler.toml

wrangler.toml 文件是您 Worker 项目的核心配置文件。它定义了 Worker 的元数据和运行时行为。

一个基本的 wrangler.toml 文件可能看起来像这样：
“`toml
name = “my-first-worker” # Worker 的名称
main = “src/index.js” # Worker 代码的入口文件
compatibility_date = “2023-11-21” # 兼容性日期，用于启用新功能或行为
account_id = “YOUR_CLOUDFLARE_ACCOUNT_ID” # 您的 Cloudflare 账户 ID

routes = [

{ pattern = “example.com/*”, zone_name = “example.com” }

]

``
*name：您的 Worker 的唯一名称。
*main：Worker 代码的入口文件路径。
*compatibility_date：一个日期字符串，用于指定 Worker 运行时应遵循的兼容性日期。这有助于确保您的 Worker 在 Cloudflare 平台更新时保持一致的行为。
*account_id：您的 Cloudflare 账户 ID。您可以在 Cloudflare 控制台的 Workers 页面找到它，或者运行wrangler whoami命令获取。
*routes` (可选)：用于将特定 URL 模式路由到您的 Worker。

8. 部署 Worker

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

在项目根目录中运行部署命令：
bash
wrangler deploy
Wrangler 会将您的代码打包并上传到 Cloudflare。部署成功后，您将获得一个 workers.dev 子域名，例如 my-first-worker.your-subdomain.workers.dev。

访问已部署的 Worker

在浏览器中访问 Wrangler 提供的 URL，您将看到您的 Worker 正在全球边缘运行。

9. 进阶功能

Cloudflare Workers 提供了丰富的进阶功能，可以帮助您构建更复杂的应用程序。

KV 存储

Cloudflare Workers KV 是一个低延迟的键值存储，可在 Cloudflare 的全球网络中提供数据存储。它非常适合存储不经常更改的参考数据或资产，并支持高读取量。

创建 KV 命名空间：
bash
wrangler kv namespace create my-kv-namespace
此命令会返回一个命名空间的 ID。您需要在 wrangler.toml 中绑定这个 KV 命名空间：
“`toml

wrangler.toml

kv_namespaces = [
{ binding = “MY_KV”, id = “YOUR_KV_NAMESPACE_ID” }
]
然后在您的 Worker 代码中访问它：javascript
// src/index.js
export default {
async fetch(request, env, ctx) {
await env.MY_KV.put(“greeting”, “Hello from KV!”);
const greeting = await env.MY_KV.get(“greeting”);
return new Response(greeting);
},
};
“`

环境变量与 Secrets

您可以使用环境变量来存储配置信息，使用 Secrets 来存储敏感信息（如 API 密钥）。

在 wrangler.toml 中定义环境变量：
“`toml

wrangler.toml

[vars]
API_URL = “https://api.example.com”
**添加 Secrets：**bash
wrangler secret put MY_API_KEY
“`
Wrangler 会提示您输入 Secret 的值。

在您的 Worker 代码中访问它们：
javascript
// src/index.js
export default {
async fetch(request, env, ctx) {
const apiUrl = env.API_URL;
const apiKey = env.MY_API_KEY; // Secrets 也会通过 env 对象访问
return new Response(`API URL: ${apiUrl}, API Key (first 3 chars): ${apiKey.substring(0, 3)}`);
},
};
请注意，.dev.vars 或 .env 文件可用于本地开发时的环境变量，但不应提交到 Git 仓库。

自定义域名

默认情况下，您的 Worker 会部署在 workers.dev 子域名下。您也可以将其绑定到您自己的自定义域名。

您可以通过 Cloudflare 控制台或 wrangler.toml 配置自定义域名。

通过 wrangler.toml 配置：
“`toml

wrangler.toml

…

确保您的域名已添加到 Cloudflare 并在 Cloudflare DNS 中配置

并且您的 Cloudflare 账户 ID 已正确设置

routes = [
{ pattern = “your-custom-domain.com/*”, zone_id = “YOUR_ZONE_ID” }
]
``
您需要将YOUR_ZONE_ID` 替换为您的 Cloudflare 区域 ID。

10. 总结

恭喜您！您已经完成了 Cloudflare Workers 的入门之旅，从环境设置到代码编写，再到部署和了解一些进阶功能。Cloudflare Workers 是一个强大且灵活的平台，让您能够构建高性能、可扩展的边缘应用程序。继续探索 Cloudflare 的文档，了解更多功能，如 Durable Objects、R2 存储、D1 数据库等，以构建更强大的应用。

滚动至顶部