# Cloudflare 工作人员 ## 概述 Cloudflare Workers 是一个无服务器执行环境，可在 Cloudflare 的全球网络上运行 JavaScript、TypeScript、Python 和 Rust 代码。 Workers 以毫秒为单位执行，自动扩展，并通过绑定与 Cloudflare 的存储和计算产品集成。 **主要优点：** * **零冷启动** \- Workers 在 V8 隔离区中运行，而不是在容器中运行 * **全球部署** \- 代码在全球 300 多个城市运行 * **丰富的生态系统** \- 绑定到 D1、KV、R2、持久对象、队列、容器、工作流等 * **全栈能力** \- 在一个项目中构建 API 并提供静态资产 * **基于标准** \- 使用 Web API（获取、加密、流、WebSockets） ## 何时使用此技能将 Cloudflare Workers 用于： * **API 和后端** \- RESTful API、GraphQL、tRPC、WebSocket 服务器 * **全栈应用程序** \- React、Next.js、Remix、Astro、Vue、Svelte 以及静态资源 * **边缘中间件** \- 身份验证、速率限制、A/B 测试、路由 * **后台处理** \- 计划作业 (cron)、队列消费者、webhooks * **数据转换** \- ETL管道，实时数据处理 * **人工智能应用** \- RAG 系统、聊天机器人、使用 Workers AI 生成图像 * **持久的工作流程** \- 具有自动重试功能的多步骤长时间运行任务（工作流程） * **容器工作负载** \- 与 Workers（容器）一起运行 Docker 容器 * **MCP 服务器** \- 托管远程模型上下文协议服务器 * **代理和网关** \- API 网关、内容转换、协议转换 ## 快速启动工作流程 ### 1\.安装牧马人 CLI npm install -g 牧马人 # 登录 Cloudflare 牧马人登录 ### 2\.创建一个新工人 # 使用 C3 (create-cloudflare) - 推荐 npm 创建 cloudflare@latest my-worker # 或者手动创建牧马人初始化我的工人 cd 我的工人 ### 3\.写你的工人 **基本 HTTP API (TypeScript)：** 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { const url = 新 URL(request.url); if (url.pathname === "/api/hello") { return Response.json({ message: "来自工人的问候！" }); } return new Response("未找到", { status: 404 }); }, }; **有环境变量和KV：** 接口环境{ MY_VAR：字符串； MY_KV: KV命名空间； } 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { // 访问环境变量 const 问候语 = env.MY_VAR; // 从KV读取 const value = wait env.MY_KV.get("my-key"); 返回 Response.json({ 问候语, 值 }); }, }; ### 4\.本地开发 # 通过热重载启动本地开发服务器牧马人开发者 # 通过http://localhost:8787访问 ### 5\.部署到生产环境 # 部署到workers.dev子域牧马人部署 # 部署到自定义域（在 wrangler.toml 中配置）牧马人部署 ## 核心概念 ### 工人运行时 Workers 使用 V8 JavaScript 引擎和 Web 标准 API： * **执行模型**：隔离（不是容器）-即时冷启动 * **CPU 时间限制** ：每个请求 10 毫秒（免费），30 秒（付费） * **内存限制**：每个隔离 128 MB * **语言**：JavaScript、TypeScript、Python、Rust * **API** ：获取、加密、流、WebSockets、WebAssembly **支持的API：** * 获取API（HTTP请求） * URL API（URL解析） * 网络加密（加密、散列） * Streams API（数据流） * WebSockets（实时通信） * 缓存API（边缘缓存） * HTML 重写器（HTML 转换） ### 处理程序工作人员通过处理程序响应事件： **获取处理程序**（HTTP 请求）：导出默认值{ 异步获取（请求：请求，env：Env，ctx：ExecutionContext）{ 返回新的响应（“你好！”）； }, }; **计划处理程序**（cron 作业）：导出默认值{ 异步计划（事件：ScheduledEvent，env：Env，ctx：ExecutionContext）{ // 按照 wrangler.toml 中定义的时间表运行等待 env.MY_KV.put("上次运行", new Date().toISOString()); }, }; **队列处理程序**（消息处理）：导出默认值{ 异步队列(batch: MessageBatch, env: Env, ctx: ExecutionContext) { for (batch.messages 的常量消息) { 等待 processMessage(message.body); 消息.ack(); } }, }; ### 绑定绑定将您的 Worker 连接到 Cloudflare 资源。在 `wrangler.toml` 中配置： **KV（键值存储）：** [[kv_命名空间]] 绑定=“MY_KV” id = "你的-kv-命名空间-id" // 用法等待 env.MY_KV.put("键", "值"); const value = wait env.MY_KV.get("key"); **D1（SQL 数据库）：** [[d1_数据库]] 绑定=“DB” 数据库名称=“我的数据库” 数据库ID =“您的数据库ID” // 用法 const 结果 = 等待 env.DB.prepare( “从 id = 的用户中选择 *” ).bind(userId).all(); **R2（对象存储）：** [[r2_buckets]] 绑定=“MY_BUCKET” Bucket_name = “我的存储桶” // 用法等待 env.MY_BUCKET.put("file.txt", "contents"); const object = wait env.MY_BUCKET.get("file.txt"); const text =等待对象？.text(); **环境变量：** [变量] API_KEY = "development-key" # pragma: 白名单秘密 **秘密**（敏感数据）： # 通过 CLI 设置（不在 wrangler.toml 中）牧马人秘放 API_KEY ### 上下文（ctx） `ctx` 参数提供对请求生命周期的控制：导出默认值{ 异步获取（请求：请求，env：Env，ctx：ExecutionContext）{ // 发送响应后运行任务 ctx.waitUntil( env.MY_KV.put("请求计数", String(Date.now())) ）； // 异常时传递到原点 ctx.passThroughOnException(); 返回新的响应（“确定”）； }, }; ### 顶级环境访问自 2025 年 3 月起，您可以在模块级别导入 `env`，而不是通过处理程序传递它：从“cloudflare:workers”导入{env}； // 访问处理程序外部的绑定 const apiClient = new ApiClient({ apiKey: env.API_KEY }); 导出默认值{ 异步获取（请求：请求）：Promise { // env 在这里也可以不带参数 const 数据 = 等待 env.MY_KV.get("config"); 返回 Response.json({ 数据 }); }, }; 这消除了通过函数签名进行 prop-drilling 'env' 并启用模块级初始化。 ## 快速发展模式 ### 牧马人配置 **必需的`wrangler.toml`：** 名称 =“我的工人” 主要=“src/index.ts” 兼容性_日期=“2025-09-01” # 自定义域路线=[ { 模式 = "api.example.com/*", zone_name = "example.com" } ] # 或者workers.dev子域工人_dev =真 # 环境变量 [变量] 环境=“生产” # 绑定 [[kv_命名空间]] 绑定=“缓存” id = "你的-kv-id" [[d1_数据库]] 绑定=“DB” 数据库名称=“生产数据库” 数据库 ID =“您的数据库 ID” [[r2_buckets]] 绑定=“资产” Bucket_name = “我的资产” # 定时任务触发器 [触发] crons = ["0 0 * * *"] # 每天午夜 ### 环境管理使用暂存/生产环境： [环境分期] vars = {环境=“分期”} [env.staging.d1_数据库] 绑定=“DB” 数据库名称=“暂存数据库” 数据库 ID =“暂存数据库 ID” [环境生产] vars = { 环境 = "生产" } [env.生产.d1_数据库] 绑定=“DB” 数据库名称=“生产数据库” 数据库 ID =“生产数据库 ID” # 部署到暂存区牧马人部署--env staging # 部署到生产环境牧马人部署 --env 生产 ### 常见模式 **具有错误处理功能的 JSON API：** 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { 尝试{ const url = 新 URL(request.url); if (url.pathname === "/api/users" && request.method === "GET") { const users = wait env.DB.prepare("SELECT * FROM users").all(); 返回 Response.json(users.results); } if (url.pathname === "/api/users" && request.method === "POST") { const body =等待request.json(); 等待 env.DB.prepare( “插入用户（姓名、电子邮件）值（？、？）” ).bind(body.name, body.email).run(); 返回 Response.json({ success: true }, { status: 201 }); } 返回 Response.json({ 错误: "未找到" }, { 状态: 404 }); } 捕获（错误）{ 返回响应.json( { 错误：错误消息 }, { 状态：500 } ）； } }, }; **身份验证中间件：** 异步函数authenticate(request:Request, env:Env): Promise { const authHeader = request.headers.get("授权"); if (!authHeader?.startsWith("Bearer ")) { 返回空值； } const 令牌 = authHeader.substring(7); const userId = wait env.SESSIONS.get(token); 返回用户ID； } 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { const userId = 等待身份验证（请求，env）； if (!userId) { return Response.json({ 错误: "未经授权" }, { 状态: 401 }); } // 继续处理经过身份验证的请求返回 Response.json({ userId }); }, }; **CORS 标头：** 常量 corsHeaders = { “访问控制允许来源”：“*”， "Access-Control-Allow-Methods": "GET、POST、PUT、DELETE、OPTIONS", "Access-Control-Allow-Headers": "内容类型，授权", }; 导出默认值{ 异步获取（请求：请求）：Promise { if (request.method === "选项") { 返回新的响应(null, { headers: corsHeaders }); } const 响应=等待handleRequest(请求); // 将 CORS 标头添加到响应中 Object.entries(corsHeaders).forEach(([键, 值]) => { 响应.headers.set（键，值）； }); 返回响应； }, }; ### 静态资产（全栈应用程序）与 Worker 代码一起提供静态文件： [资产] 目录=“./public” 绑定=“资产” 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { const url = 新 URL(request.url); // API 路由 if (url.pathname.startsWith("/api/")) { 返回handleAPI（请求，环境）； } // 通过 ASSETS 绑定提供静态资源返回 env.ASSETS.fetch(请求); }, }; ### 测试 **使用维测试：** 从“cloudflare:test”导入{ env, createExecutionContext }；从“vtest”导入{描述，它，期望}；从“./index”导入工人；描述（“工人”，（）=> { it("用 JSON 响应", async () => { const request = new Request("http://example.com/api/hello"); const ctx = createExecutionContext(); constresponse=awaitworker.fetch(request,env,ctx); 期望(响应.状态).toBe(200); Expect(await response.json()).toEqual({ message: "你好！" }); }); }); ## 框架集成 Workers 通过适配器支持主要框架： * **Next.js** \- 完整的应用程序路由器和页面路由器支持 * **Remix / React Router** \- 原生 Cloudflare 适配器 * **Astro** \- Workers 上的服务器端渲染 * **SvelteKit** \- Cloudflare 适配器可用 * **Hono** \- 为 Workers 构建的轻量级 Web 框架 * **tRPC** \- 具有完整 Workers 支持的类型安全 API **以 Hono 为例：** 从“hono”导入{Hono}； const app = new Hono(); app.get("/", (c) => c.text("你好！")); app.get("/api/users/:id", async (c) => { const id = c.req.param("id"); const 用户 = 等待 c.env.DB.prepare( “从 id = 的用户中选择 *” ).bind(id).first(); 返回 c.json(用户); }); 导出默认应用程序； ## 高级主题有关高级功能的详细信息，请参阅参考文件： * **完整绑定指南** : `references/bindings-complete-guide.md` \- 所有绑定类型（D1、KV、R2、持久对象、队列、Workers AI、Vectorize、工作流、容器、Secrets Store、Pipelines、AutoRAG） * **部署和 CI/CD**：`references/wrangler-and-deployment.md` \- Wrangler v4 迁移、命令、GitHub Actions、GitLab CI/CD、逐步部署、远程绑定 * **开发最佳实践** : `references/development-patterns.md` \- 测试、调试、错误处理、性能、顶级环境访问模式 * **高级功能** : `references/advanced-features.md` \- 容器、工作流程、MCP 服务器、平台工作人员、WebSockets、Node.js 兼容、流媒体 * **可观察性** : `references/observability.md` \- 日志记录（tail、Logpush、Workers Logs）、指标、跟踪、调试 ## 资源 **官方文档：** * 工作人员： * Wrangler CLI： * 运行时 API： * 示例： * 工作流程： * 容器： **模板和快速入门：** * 模板： * 框架指南： **社区：** * 不和谐： * GitHub：

Cloudflare 工人

包含技能