用途:Vercel Queues 提供持久化、仅追加的消息主题,用于后台任务与智能体事件。生产者发布 JSON 消息,每个订阅的消费者组都会收到每条消息,采用至少一次投递并自动重试;新消费者组可稍后加入并重放未过期历史。它是 Vercel Workflows 的底层原语,需要自行控制发布、消费与路由时可直接使用。
主要能力:主题在首次发布时创建;消费者组相互独立;默认保留 24 小时,最长 7 天,投递可延迟至保留期内;支持 push(Vercel 调用函数)或 poll(自有 worker 从任意环境拉取)两种模式。send 支持 region、retentionSeconds(最小 60,最大 604800)、delaySeconds、idempotencyKey、headers 等选项。handleCallback 支持 visibilityTimeoutSeconds(默认 300)与 retry 策略,可基于 deliveryCount 确认毒消息。metadata 含 messageId、deliveryCount、createdAt、expiresAt、topicName、consumerGroup、region。
使用方式:安装 npm install @vercel/queue;用 send 发布,用 handleCallback 消费,并在 vercel.json 或 vercel.ts 的 experimentalTriggers 中注册消费者(type 为 queue/v2beta)。本地开发前先运行 vercel link 和 vercel env pull。Express/Connect/Next.js Pages Router 可用 queue.handleNodeCallback。Python 用 vercel-queue,支持 FastAPI、Flask、Django;Nitro/Nuxt 在 nitro.config.ts 声明 vercel.queues.triggers。二进制或大体积负载可用 BufferTransport、StreamTransport。
适用场景:即发即忘的后台任务、扇出、缓冲;需要多步逻辑(sleep、钩子、人工审批)时应改用 Workflows;定时触发应使用 Cron Jobs。
限制与注意:投递为至少一次,处理器必须幂等;未注册触发器的路由收不到消息;无重试策略或 maxDeliveries 上限时,永久失败消息会重投至过期;重复幂等键会被静默丢弃而不报错;缺少凭据时 send 会抛出 OIDC 令牌错误。错误类型包括 UnauthorizedError、BadRequestError、MessageNotFoundError、QueueEmptyError。定价与限额见官方文档。