cloudflare-workers_IT运维与安全 skill-PHP中文网

cloudflare-workers

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

使用 Cloudflare Workers 快速开发——在 Cloudflare 全球网络上构建并部署无服务器应用。适用于构建 API、全栈 Web 应用...

Cloudflare Workers.

功能概述

Cloudflare Workers.是一项面向实际任务的技能，主要用于Overview.；Cloudflare Workers是一个无服务器的执行环境,运行在Cloudflare的全球网络上JavaScript,TypeScript,Python,以及Rust代码. .；

核心要点

Workers expert in m.。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。

使用与执行

从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。

Cloudflare Workers

概述

Cloudflare Workers 是一个无服务器执行环境，可在 Cloudflare 全球网络上运行 JavaScript、TypeScript、Python 和 Rust 代码。Workers 在毫秒级内启动，自动扩缩容，并通过绑定（bindings）与 Cloudflare 的存储和计算产品深度集成。

核心优势：

零冷启动 — Workers 运行于 V8 隔离环境（isolates），而非容器
全球部署 — 代码在遍布全球 300 多个城市的边缘节点运行
丰富生态 — 支持 D1、KV、R2、Durable Objects、Queues、Containers、Workflows 等多种绑定
全栈能力 — 单个项目即可构建 API 并托管静态资源
标准兼容 — 原生支持 Web 标准 API（fetch、crypto、streams、WebSockets）

适用场景

以下场景推荐使用 Cloudflare Workers：

API 与后端服务 — RESTful API、GraphQL、tRPC、WebSocket 服务器
全栈应用 — React、Next.js、Remix、Astro、Vue、Svelte 等框架搭配静态资源托管
边缘中间件 — 身份认证、速率限制、A/B 测试、动态路由
后台任务处理 — 定时任务（cron）、队列消费者、Webhook 接收器
数据转换 — ETL 流水线、实时数据处理
AI 应用 — RAG 系统、聊天机器人、基于 Workers AI 的图像生成
持久化工作流 — 支持自动重试的多步骤长周期任务（Workflows）
容器化工作负载 — 在 Workers 旁运行 Docker 容器（Containers）
MCP 服务器 — 托管远程 Model Context Protocol 服务器
代理与网关 — API 网关、内容变换、协议转换

快速入门流程

1. 安装 Wrangler CLI

npm install -g wrangler

# 登录 Cloudflare 账户
wrangler login

2. 创建新 Worker

# 推荐方式：使用 C3（create-cloudflare）
npm create cloudflare@latest my-worker

# 或手动创建
wrangler init my-worker
cd my-worker

3. 编写 Worker 逻辑

基础 HTTP API（TypeScript）：

export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url);

    if (url.pathname === "/api/hello") {
      return Response.json({ message: "Hello from Workers!" });
    }

    return new Response("Not found", { status: 404 });
  },
};

结合环境变量与 KV：

interface Env {
  MY_VAR: string;
  MY_KV: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise {
    // 访问环境变量
    const greeting = env.MY_VAR;

    // 从 KV 读取数据
    const value = await env.MY_KV.get("my-key");

    return Response.json({ greeting, value });
  },
};

4. 本地开发

# 启动本地开发服务器（支持热重载）
wrangler dev

# 访问地址：http://localhost:8787

5. 部署至生产环境

# 部署到 workers.dev 子域名
wrangler deploy

# 部署到自定义域名（需在 wrangler.toml 中配置）
wrangler deploy

核心概念

Workers 运行时

Workers 基于 V8 JavaScript 引擎，并原生支持 Web 标准 API：

执行模型：隔离环境（isolates），非容器 — 实现即时冷启动
CPU 时间限制：每次请求 10ms（免费版），30 秒（付费版）
内存限制：每个 isolate 最高 128 MB
支持语言：JavaScript、TypeScript、Python、Rust
可用 API：fetch、crypto、streams、WebSockets、WebAssembly

支持的 Web API：

Fetch API（发起 HTTP 请求）
URL API（URL 解析）
Web Crypto（加解密、哈希）
Streams API（数据流处理）
WebSockets（实时双向通信）
Cache API（边缘缓存控制）
HTML Rewriter（HTML 内容改写）

处理器（Handlers）

Workers 通过不同事件处理器响应各类事件：

Fetch 处理器（HTTP 请求）：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return new Response("Hello!");
  },
};

Scheduled 处理器（定时任务）：

export default {
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    // 按 wrangler.toml 中定义的时间表执行
    await env.MY_KV.put("last-run", new Date().toISOString());
  },
};

Queue 处理器（消息队列消费）：

export default {
  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
    for (const message of batch.messages) {
      await processMessage(message.body);
      message.ack();
    }
  },
};

绑定（Bindings）

绑定用于将 Worker 连接到 Cloudflare 各类资源，需在 wrangler.toml 中配置：

KV（键值存储）：

[[kv_namespaces]]
binding = "MY_KV"
id = "your-kv-namespace-id"

// 使用示例
await env.MY_KV.put("key", "value");
const value = await env.MY_KV.get("key");

D1（SQL 数据库）：

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id"

// 使用示例
const result = await env.DB.prepare(
  "SELECT * FROM users WHERE id = ?"
).bind(userId).all();

R2（对象存储）：

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

// 使用示例
await env.MY_BUCKET.put("file.txt", "contents");
const object = await env.MY_BUCKET.get("file.txt");
const text = await object?.text();

环境变量：

[vars]
API_KEY = "development-key"  # pragma: allowlist secret

密钥（Secrets）（敏感信息）：

# 通过 CLI 设置（不写入 wrangler.toml）
wrangler secret put API_KEY

上下文（ctx）

ctx 参数提供对请求生命周期的精细控制：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // 在响应发送后异步执行任务
    ctx.waitUntil(
      env.MY_KV.put("request-count", String(Date.now()))
    );

    // 出现异常时透传至源站
    ctx.passThroughOnException();

    return new Response("OK");
  },
};

顶层环境访问（Top-level Environment Access）

自 2025 年 3 月起，您可在模块顶层直接导入 env，无需再通过处理器参数传递：

import { env } from "cloudflare:workers";

// 在处理器外部访问绑定
const apiClient = new ApiClient({ apiKey: env.API_KEY });

export default {
  async fetch(request: Request): Promise {
    // 此处亦可直接使用 env，无需声明参数
    const data = await env.MY_KV.get("config");
    return Response.json({ data });
  },
};

此举避免了函数签名中冗余的 env 参数传递（prop-drilling），并支持模块级初始化逻辑。

高效开发模式

Wrangler 配置

精简版 wrangler.toml 示例：

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-09-01"

# 自定义域名路由
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

# 或启用 workers.dev 子域名
workers_dev = true

# 环境变量
[vars]
ENVIRONMENT = "production"

# 绑定配置
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

[[d1_databases]]
binding = "DB"
database_name = "production-db"
database_id = "your-db-id"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

# 定时触发器
[triggers]
crons = ["0 0 * * *"]  # 每日午夜执行

环境管理

通过环境区分预发布（staging）与生产（production）：

[env.staging]
vars = { ENVIRONMENT = "staging" }

[env.staging.d1_databases]
binding = "DB"
database_name = "staging-db"
database_id = "staging-db-id"

[env.production]
vars = { ENVIRONMENT = "production" }

[env.production.d1_databases]
binding = "DB"
database_name = "production-db"
database_id = "production-db-id"

# 部署至 staging 环境
wrangler deploy --env staging

# 部署至 production 环境
wrangler deploy --env production

常用开发模式

带错误处理的 JSON API：

export default {
  async fetch(request: Request, env: Env): Promise {
    try {
      const url = new URL(request.url);

      if (url.pathname === "/api/users" && request.method === "GET") {
        const users = await env.DB.prepare("SELECT * FROM users").all();
        return Response.json(users.results);
      }

      if (url.pathname === "/api/users" && request.method === "POST") {
        const body = await request.json();
        await env.DB.prepare(
          "INSERT INTO users (name, email) VALUES (?, ?)"
        ).bind(body.name, body.email).run();
        return Response.json({ success: true }, { status: 201 });
      }

      return Response.json({ error: "Not found" }, { status: 404 });
    } catch (error) {
      return Response.json(
        { error: error.message },
        { status: 500 }
      );
    }
  },
};

身份认证中间件：

async function authenticate(request: Request, env: Env): Promise {
  const authHeader = request.headers.get("Authorization");
  if (!authHeader?.startsWith("Bearer ")) {
    return null;
  }

  const token = authHeader.substring(7);
  const userId = await env.SESSIONS.get(token);
  return userId;
}

export default {
  async fetch(request: Request, env: Env): Promise {
    const userId = await authenticate(request, env);

    if (!userId) {
      return Response.json({ error: "Unauthorized" }, { status: 401 });
    }

    // 继续处理已认证请求
    return Response.json({ userId });
  },
};

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 {
    if (request.method === "OPTIONS") {
      return new Response(null, { headers: corsHeaders });
    }

    const response = await handleRequest(request);

    // 向响应添加 CORS 头
    Object.entries(corsHeaders).forEach(([key, value]) => {
      response.headers.set(key, value);
    });

    return response;
  },
};

静态资源托管（全栈应用）

将静态文件与 Worker 代码一同部署：

[assets]
directory = "./public"
binding = "ASSETS"

export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url);

    // API 路由
    if (url.pathname.startsWith("/api/")) {
      return handleAPI(request, env);
    }

    // 通过 ASSETS 绑定提供静态资源
    return env.ASSETS.fetch(request);
  },
};

测试

使用 Vitest：

import { env, createExecutionContext } from "cloudflare:test";
import { describe, it, expect } from "vitest";
import worker from "./index";

describe("Worker", () => {
  it("responds with JSON", async () => {
    const request = new Request("http://example.com/api/hello");
    const ctx = createExecutionContext();
    const response = await worker.fetch(request, env, ctx);

    expect(response.status).toBe(200);
    expect(await response.json()).toEqual({ message: "Hello!" });
  });
});

框架集成

Workers 原生支持主流框架（通过适配器）：

Next.js — 完整支持 App Router 与 Pages Router
Remix / React Router — 官方 Cloudflare 适配器
Astro — 在 Workers 上实现服务端渲染（SSR）
SvelteKit — 提供 Cloudflare 适配器
Hono — 专为 Workers 设计的轻量级 Web 框架
tRPC — 类型安全 API，完整支持 Workers

Hono 示例：

import { Hono } from "hono";

const app = new Hono();

app.get("/", (c) => c.text("Hello!"));
app.get("/api/users/:id", async (c) => {
  const id = c.req.param("id");
  const user = await c.env.DB.prepare(
    "SELECT * FROM users WHERE id = ?"
  ).bind(id).first();
  return c.json(user);
});

export default app;

进阶主题

如需了解高级功能的详细说明，请参阅以下参考文档：

完整绑定指南：references/bindings-complete-guide.md — 涵盖全部绑定类型（D1、KV、R2、Durable Objects、Queues、Workers AI、Vectorize、Workflows、Containers、Secrets Store、Pipelines、AutoRAG）
部署与 CI/CD：references/wrangler-and-deployment.md — Wrangler v4 迁移指南、命令详解、GitHub Actions 集成、GitLab CI/CD、渐进式发布、远程绑定配置
开发最佳实践：references/development-patterns.md — 测试策略、调试技巧、错误处理、性能优化、顶层 env 访问模式
高级特性：references/advanced-features.md — Containers、Workflows、MCP 服务器、Workers for Platforms、WebSockets、Node.js 兼容性、流式响应
可观测性：references/observability.md — 日志（tail、Logpush、Workers Logs）、指标（metrics）、链路追踪（traces）、调试方法