cloudflare-queues

用途

Cloudflare Queues 技能用于在 Cloudflare Workers 环境中设置和使用消息队列。当用户需要搭建 Cloudflare Queues、创建消息队列、实现队列消费者、处理后台任务时，可使用该技能。它依赖 cloudflare-worker-base（用于 Worker 设置）。

主要能力

快速上手：创建队列、编写生产者发送消息、编写消费者处理消息、部署。
关键规则：包括始终配置死信队列、对非幂等操作使用显式 ack()、发送前校验消息大小、使用 sendBatch() 批量发送、实现指数退避重试、根据负载设置批量参数、监控队列积压与消费者错误、在消费者中使用 ctx.waitUntil() 进行异步清理、优雅处理错误、让并发自动扩展等。
常见错误与解决方案：消息过大（超过 128 KB）、吞吐量超限（每队列每秒 5000 条）、单条消息失败导致整批重试等。
典型使用场景：基础消息队列、数据库写入（非幂等）、带指数退避的重试、死信队列模式、高吞吐处理。
配置参考：生产者与消费者在 wrangler.jsonc 中的配置方式，CPU 限制调整。
限制与配额：消息大小 128 KB、吞吐量 5000 条/秒、sendBatch() 每批最多 100 条、消费者 CPU 时间默认 30 秒（可配置最大 300 秒）、最大重试次数可配置（默认 3）、队列名称最多 63 字符（小写字母/数字/连字符）。
监控与调试：wrangler queues info、wrangler tail、wrangler queues pause-delivery/resume-delivery 等命令。
生产检查清单：12 项部署前检查，涵盖死信队列、消息确认策略、大小校验、批量优化、并发设置、CPU 限制、错误处理、监控、限流、幂等性、负载测试和安全审查。

使用方式

创建队列：使用 bunx wrangler queues create my-queue，并用 bunx wrangler queues list 查看。
生产者：在 wrangler.jsonc 的 queues.producers 数组中添加绑定与队列名，在代码中通过 env.MY_QUEUE.send() 发送消息。
消费者：在 wrangler.jsonc 的 queues.consumers 数组中配置 queue、max_batch_size、max_retries、dead_letter_queue 等，在代码中导出 queue(batch) 处理函数。
部署：使用 bunx wrangler deploy。

技能还提供配套资源：references/ 下的 setup-guide.md、error-catalog.md、producer-api.md、consumer-api.md、best-practices.md、wrangler-commands.md、typescript-types.md、production-checklist.md、pull-consumers.md、http-publishing.md、r2-event-integration.md；templates/ 下的生产者、消费者、重试、死信队列模板及生产配置；以及 queue-debugger、queue-optimizer 代理和 /queue-setup、/queue-troubleshoot、/queue-monitor 命令。

适用场景

简单异步任务处理（邮件、通知）。
数据库写入等非幂等操作，需避免重复。
调用有限流 API 或临时失败时的重试与指数退避。
生产系统中捕获永久失败消息的死信队列模式。
每秒处理数千条消息的高吞吐场景。
从非 Workers 环境（Node.js、Python、Go）拉取消费。
通过 HTTP 从外部系统发布消息。
基于 R2 桶事件触发队列消息。

限制

消息大小上限 128 KB；每队列吞吐量上限 5000 条/秒；sendBatch() 每批最多 100 条；消费者 CPU 时间默认 30 秒，可配置最大 300 秒；最大重试次数可配置，默认 3；队列名称最多 63 字符，仅小写字母、数字和连字符。消息顺序不保证 FIFO。

技能介绍

用途

主要能力

使用方式

适用场景

限制

相关技能