【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载Cloudflare Workers 运行在遍布全球 300 数据中心的 V8 Isolates 之上而非容器或虚拟机提供亚毫秒级冷启动与 Web 标准兼容的运行时fetch、URL、Headers、Request、Response一应俱全。本文以 autoskills 仓库中cloudflare-deploy技能的 Workers Runtime APIs 参考文档 为核心骨架系统拆解 Worker 的入口处理器、执行上下文、各类 BindingsKV / R2 / D1 / Queues / Secrets、缓存与 HTML 流式改写、WebSocket 生命周期、Durable Objects 的状态协调以及 Worker 间通信并补充 配置参考、常见陷阱 与最佳模式 中的源码级细节。读完本文你将能够独立编写、绑定、部署并调优一个生产级的 Cloudflare Workers 应用。入口Fetch Handler 与请求路由Worker 的核心入口是模块化 Worker 模式Module Worker Pattern官方推荐导出的默认对象。所有入站 HTTP 请求都会进入fetch方法export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { const url new URL(request.url); if (request.method POST url.pathname /api) { const body await request.json(); return new Response(JSON.stringify({ id: 1 }), { headers: { Content-Type: application/json } }); } return fetch(request); // Subrequest to origin }, };三个入参各司其职详见 Workers README参数含义request标准Request对象包含方法、URL、Headers 与 body 流env环境绑定对象KV、D1、R2、Queues、Secrets、Vars 等全部挂载于此ctxExecutionContext提供waitUntil与passThroughOnException除fetch外Worker 还支持其他入口处理器签名如下// HTTP requests async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse // Cron triggers async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promisevoid // Queue consumer async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promisevoid // Tail consumer async tail(events: TraceItem[], env: Env, ctx: ExecutionContext): Promisevoid上述示例中的return fetch(request)是回源子请求Subrequest to origin的经典写法常用于在边缘做鉴权、改写、A/B 测试后再将请求转发给源站。注意fetch不能在模块全局作用域调用会触发 Cannot fetch in global scope 错误必须放在处理器函数内部详见 gotchas.md。执行上下文waitUntil 与 passThroughOnExceptionExecutionContext是 Worker 处理后台任务的官方通道ctx.waitUntil(logAnalytics(request)); // Background work, dont block response ctx.passThroughOnException(); // Failover to origin on errorctx.waitUntil(promise)把异步任务挂到当前请求生命周期之外执行。它不会阻塞响应返回但能保证在 Worker 冻结前完成——适合埋点上报、缓存预热、日志写入等后台工作。ctx.passThroughOnException()注册一个兜底开关——若后续处理抛出未捕获异常Worker 会把请求自动转发给源站failover to origin而不是返回 500。铁律永远不要await后台操作否则它们会阻塞响应、白白消耗 CPU 时间。CPU 时间限制是 10ms标准 Worker/ 30msUnbound Worker超时会触发 Too much CPU time used 错误见 gotchas.md。Bindings连接存储与外部服务的统一入口env上挂载的一切资源统称 Bindings它们必须在 wrangler.jsonc 配置 中预先声明。API 层的典型用法如下// KV await env.MY_KV.get(key); await env.MY_KV.put(key, value, { expirationTtl: 3600 }); // R2 const obj await env.MY_BUCKET.get(file.txt); await env.MY_BUCKET.put(file.txt, content); // D1 const result await env.DB.prepare(SELECT * FROM users WHERE id ?).bind(1).first(); // D1 Sessions (2024) - read-after-write consistency const session env.DB.withSession(); await session.prepare(INSERT INTO users (name) VALUES (?)).bind(Alice).run(); const user await session.prepare(SELECT * FROM users WHERE name ?).bind(Alice).first(); // Guaranteed fresh // Queues await env.MY_QUEUE.send({ timestamp: Date.now() }); // Secrets/vars const key env.API_KEY;各类 Bindings 的配置要点对应配置片段完整示例见 configuration.md{ // 环境变量 - 通过 env.VAR_NAME 访问 vars: { ENVIRONMENT: production }, // KV键值存储 kv_namespaces: [{ binding: MY_KV, id: abc123 }], // R2对象存储 r2_buckets: [{ binding: MY_BUCKET, bucket_name: my-bucket }], // D1SQL 数据库 d1_databases: [{ binding: DB, database_name: my-db, database_id: xyz789 }], // Queues消息队列 queues: { producers: [{ binding: MY_QUEUE, queue: my-queue }], consumers: [{ queue: my-queue, max_batch_size: 10 }] }, // Service bindingsWorker 间 RPC services: [{ binding: SERVICE_B, service: service-b }] }关键语义KV全局分布式、最终一致约 60s 传播的读优化存储单 key 写入速率约 1 次/秒单值上限 25 MiB适合配置、会话、特性开关、缓存详见 KV README。D1SQLite 关系型数据库。默认最终一致写入后立刻读取可能看不到最新数据D1 Sessions2024在会话内提供 read-after-write 强一致适用于写→读和需要事务一致性的场景见 gotchas.md。R2S3 兼容对象存储超大文件100MB应使用createMultipartUpload分片上传见 patterns.md。Secrets绝不写入配置文件只能通过 CLI 注入npx wrangler secret put API_KEY代码中通过env.API_KEY读取。自动供应Beta绑定可以只写binding名不写id部署时自动创建资源{ kv_namespaces: [{ binding: MY_KV }] }。类型安全让env全类型化推荐使用自动类型生成见 configuration.mdnpm install -D cloudflare/workers-types npx wrangler types # 从 wrangler.jsonc 生成 .wrangler/types/runtime.d.tsimport type { Env } from ./.wrangler/types/runtime; export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { await env.MY_KV.get(key); // 全类型提示自动补全可用 return new Response(OK); }, };每次修改wrangler.jsonc中的绑定后都要重新运行npx wrangler types。tsconfig.json中需要包含.wrangler/types/**/*.ts。Cache API边缘缓存的手动控制Workers 提供与浏览器 Cache API 同构的运行时缓存caches.default即默认缓存空间const cache caches.default; let response await cache.match(request); if (!response) { response await fetch(request); response new Response(response.body, response); response.headers.set(Cache-Control, max-age3600); ctx.waitUntil(cache.put(request, response.clone())); // Clone before caching }三个容易被忽略的细节先克隆再缓存response是流stream消费过一次就不能再用所以写入缓存前必须response.clone()。重建 Responsenew Response(response.body, response)可以把原响应浅拷贝成可修改的新对象用于设置Cache-Control等头。用ctx.waitUntil包住缓存写入写入不必阻塞本次响应让它在后台完成。与之呼应gotchas.md中的 Body has already been used 错误正是 body 流只能读一次所致解决方案就是response.clone()或读取一次后用文本重建 Response。HTMLRewriter流式改写 HTMLHTMLRewriter是 Workers 独有的流式 HTML 处理 API——在响应流经边缘时按选择器改写元素不需要先把整个 HTML 下载到内存return new HTMLRewriter() .on(a[href], { element(el) { const href el.getAttribute(href); if (href?.startsWith(http://)) { el.setAttribute(href, href.replace(http://, https://)); } } }) .transform(response);典型用例A/B 测试注入脚本、埋点/分析代码注入、链接协议改写HTTP→HTTPS、页面元素替换。由于是流式处理它可以作用于超大页面而几乎不增加内存占用。WebSockets实时双向通信标准 WebSocketWorker 直连Worker 可以直接作为 WebSocket 服务端用WebSocketPair建立连接const [client, server] Object.values(new WebSocketPair()); server.accept(); server.addEventListener(message, event { server.send(Echo: ${event.data}); }); return new Response(null, { status: 101, webSocket: client });WebSocketPair返回一对 socketclient随 101 响应交给客户端server留在 Worker 内处理收发。WebSocket Hibernation空闲连接推荐在 Durable Object 中WebSocket 连接默认会在每次消息后唤醒对象CPU 时间持续消耗。Hibernation休眠让空闲连接进入零 CPU、零计费状态只在事件到达时唤醒// In Durable Object export class WebSocketDO { async webSocketMessage(ws: WebSocket, message: string) { ws.send(Echo: ${message}); } async webSocketClose(ws: WebSocket, code: number, reason: string) { // Cleanup on close } async webSocketError(ws: WebSocket, error: Error) { console.error(WebSocket error:, error); } }Hibernation 会自动挂起不活跃连接无 CPU 成本事件到达时再唤醒。它解决的正是gotchas.md中 WebSocket connection closes unexpectedly 的问题——Worker 在维持连接期间到达 CPU 限制导致连接被断开。注意休眠会清空内存态关键数据必须持久化见 Durable Objects README 的Rules of Durable Objects。Durable Objects强一致的有状态协调Durable ObjectsDO把计算与强一致存储捆绑在全局唯一的实例上单线程串行处理请求、无竞态、状态与计算共置。它是实时协作、限流、强一致状态的推荐方案。RPC 模式2024 推荐直接导出方法Worker 侧通过桩stub进行类型安全、零序列化开销的远程调用export class Counter { private value 0; constructor(private state: DurableObjectState) { state.blockConcurrencyWhile(async () { this.value (await state.storage.get(value)) || 0; }); } // Export methods directly - called via RPC (type-safe, zero serialization) async increment(): Promisenumber { this.value; await this.state.storage.put(value, this.value); return this.value; } async getValue(): Promisenumber { return this.value; } } // Worker usage: const stub env.COUNTER.get(env.COUNTER.idFromName(global)); const count await stub.increment(); // Direct method call, full type safety要点说明blockConcurrencyWhile保证构造函数内的初始化如从 storage 恢复状态与其他请求互斥完成。idFromName(global)生成确定性ID适合命名协调场景限流、锁、会话高吞吐场景改用newUniqueId()分片详见 Durable Objects README。现代写法中 DO 应继承DurableObjectEnv基类并使用 SQLite 存储this.ctx.storage.sql支持事务与 10GB/实例容量。旧式 Fetch 模式Pre-2024RPC 之前DO 通过stub.fetch()模拟 HTTP 调用async fetch(request: Request): PromiseResponse { const url new URL(request.url); if (url.pathname /increment) { await this.state.storage.put(value, this.value); } return new Response(String(this.value)); } // Usage: await stub.fetch(http://x/increment)gotchas.md明确警告仍在使用stub.fetch()模式的旧代码应迁移到 RPC避免序列化开销与类型丢失。适用场景对照场景推荐新项目 compatibility_date ≥ 2024-04-03RPC类型安全、更简单需要 HTTP 语义headers、statusfetch()把请求代理给 DOfetch()遗留兼容fetch()DO 使用决策实时协作、速率限制、强一致状态 → DO纯高并发读 → KV关系型 SQL → D1。其他处理器Cron / Queue / Tail除了fetchWorker 还能响应定时、队列与日志事件// Cron: async scheduled(event, env, ctx) { ctx.waitUntil(doCleanup(env)); } // Queue: async queue(batch) { for (const msg of batch.messages) { await process(msg.body); msg.ack(); } } // Tail: async tail(events, env) { for (const e of events) if (e.outcome exception) await log(e); }scheduledCron 触发器在 wrangler.jsonc 中声明triggers: { crons: [0 */6 * * *] }每 6 小时。queue消费 Queues 消息批次逐条处理并ack()确认。tailTail Workers 消费其他 Worker 的执行追踪事件常用于异常监控与日志聚合。Service BindingsWorker 到 Worker 的零延迟通信Service Bindings 让 Worker A 直接调用 Worker B不经过公网无 internet round-trip// Worker-to-worker RPC (zero latency, no internet round-trip) return env.SERVICE_B.fetch(request); // With RPC (2024) - same as Durable Objects RPC export class ServiceWorker { async getData() { return { data: value }; } } // Usage: const data await env.SERVICE_B.getData();收益类型安全的方法调用、无 HTTP 开销、可在多个 Worker 间共享代码逻辑。同时它也是解决gotchas.md中 Subrequest depth limit exceeded每请求子请求上限 1000 次的有效手段——用服务绑定替代深层嵌套的fetch链。部署与常用命令完整的开发闭环命令详见 Workers README 与 patterns.mdnpx wrangler dev # 本地开发 npx wrangler dev --remote # 远端开发使用真实资源 npx wrangler deploy # 生产部署 npx wrangler deploy --env staging # 指定环境 npx wrangler deploy --dry-run # 仅校验 npx wrangler tail # 流式查看日志 npx wrangler secret put API_KEY # 设置 Secret npx wrangler versions upload --message Add feature # 版本上传 npx wrangler rollback # 回滚部署前务必用npx wrangler whoami确认已认证见 cloudflare-deploy SKILL.md本地交互使用wrangler login一次性 OAuthCI/CD 设置CLOUDFLARE_API_TOKEN环境变量。若沙箱环境拦截了部署网络请求可携带sandbox_permissionsrequire_escalated重新执行。关键限制速查编写生产代码前请牢记下表数据来源gotchas.md限制项值备注请求大小100 MB最大入站请求响应大小不限支持流式CPU 时间标准10ms标准 WorkerCPU 时间Unbound30msUnbound Worker子请求数1000每请求KV 读取1000每请求KV 写入大小25 MB单次写入上限环境env大小5 MB全部绑定总大小延伸阅读Workers 配置指南 —— wrangler.jsonc、Bindings、环境与 TypeScript 设置Workers 通用模式 —— 错误处理、CORS、路由、校验、流式与测试Workers 框架选型 —— Hono、itty-router、Worktop 对比KV 存储 —— 键值存储D1 数据库 —— SQL 数据库R2 对象存储 —— 对象存储Durable Objects —— 有状态协调Queues —— 消息队列赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐基于 Cloudflare Workers 与 Durable Objects 搭建 tldraw 实时多人同步后端sync-cloudflare 模板全解析基于 Cloudflare Workers 与 Durable Objects 搭建 tldraw 实时多人同步后端sync cloudflare 模板全解析前端UI组件WSABuilds 安装避坑从部署到配置实操WSABuilds 安装避坑从部署到配置实操 想在 Windows 上直接跑 Android 应用却卡在官方 Windows Subsystem for A开发工具Cloudflare Workers Playground API 完全指南Handler、Request、Response 与边缘运行时核心能力Cloudflare Workers Playground API 完全指南Handler、Request、Response 与边缘运行时核心能力 Cloud人工智能AI 技能AI 插件上一篇VMware macOS虚拟机解锁终极指南Unlocker 3.0完整使用教程下一篇3步高效解决TranslucentTB开机自启失败实用完整修复指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考