cloudflare-queues

用途

Cloudflare Queues 用于在 Cloudflare 平台上构建异步消息队列，实现后台处理、批处理与重试。适合处理异步任务、批量处理数据以及需要可靠重试的场景。

主要能力

生产者 API：通过 Worker 绑定发送单条消息、带延迟消息（最长 43200 秒 / 12 小时），或批量发送（最多 100 条或 256 KB）。
HTTP 发布（2025 年 5 月起）：无需 Cloudflare Workers SDK，可从任意服务或语言（Node.js、Python、Go 等）通过 HTTP 向队列发布消息，需要具备 Queues Edit 权限的 Cloudflare API Token。
事件订阅（2025 年 8 月起）：可订阅 R2、Workers KV、Workers AI、Vectorize、Workflows、Super Slurper、Workers Builds 等 Cloudflare 服务的事件并通过队列消费，无需自建 Webhook。
消费者 API：以 Worker 的 queue 处理函数批量消费消息，提供 message.id、timestamp、body、attempts 等字段，支持 message.ack()、message.retry() 以及批量的 batch.ackAll()、batch.retryAll()。
重试与死信队列：支持指数退避重试；配置 dead_letter_queue 后，超过 max_retries 的消息进入 DLQ，否则会被永久删除。

使用方式

快速入门步骤：

创建队列：npx wrangler queues create my-queue
在 wrangler.jsonc 中为生产者添加绑定，例如 { "queues": { "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }] } }
从 Worker 发送消息：await env.MY_QUEUE.send({ userId: '123', action: 'process-order' });
添加消费者绑定：{ "queues": { "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }] } }
实现处理逻辑，使用 message.ack() 显式确认。
部署并测试：npx wrangler deploy、npx wrangler tail my-consumer。

消费者配置示例：

{
  "queues": {
    "consumers": [{
      "queue": "my-queue",
      "max_batch_size": 100,
      "max_batch_timeout": 30,
      "max_retries": 5,
      "retry_delay": 300,
      "max_concurrency": 10,
      "dead_letter_queue": "my-dlq"
    }]
  }
}

常用 Wrangler 命令包括创建、列举、查看、删除队列，以及 pause-delivery、resume-delivery、purge 和消费者管理等。

适用场景

处理异步任务与后台处理
批量处理数据
需要可靠重试的操作（如第三方 API 调用、支付、数据库写入）
从外部微服务、外部 Cron 任务或 Webhook 接收方发布消息
基于 R2 上传、KV 变更、AI 推理完成等事件构建事件驱动架构

限制与注意事项

消息大小上限 128 KB（含约 100 字节元数据），超限应存入 R2 并发送引用。
批量发送最多 100 条或 256 KB；延迟 0–43200 秒。
消息顺序不保证（非 FIFO）。
账户队列上限 10,000；消息重试上限 100；批次大小 1–100；批处理超时 0–60 秒。
生产环境建议配置 DLQ，否则失败消息在达到最大重试次数后被永久删除。
文档列出若干已知问题与规避方式：多个 dev 进程间队列不互通、wrangler dev --remote 下队列绑定返回 500、D1 remote 与队列 remote 的绑定冲突、本地/远程绑定混用导致消费者缺失、http_pull 类型导致 Worker 消费者不执行等。
delivery_delay 生产者参数将被移除，应改用逐消息 delaySeconds。
max_batch_timeout 在某些版本下可能影响本地开发。
多环境部署时队列名无法从生产者绑定获取，只能在消费者中通过 batch.queue 获取，需自行做名称归一化。

（依赖：cloudflare-worker-base；版本：wrangler@4.58.0、@cloudflare/workers-types@4.20260109.0；状态：Production Ready）

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项