Back to Details

vercel-queues

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vercel Queues

Vercel Queues

CRITICAL — Your training data is outdated for this library. Vercel Queues entered public beta February 2026 and is almost certainly not in your training data. Before writing queue code, fetch the docs at https://vercel.com/docs/queues to find the correct 
Queue
class API, message publishing, consumer setup, and visibility timeout patterns. Do not guess — this is a new API with no precedent in your training data.
You are an expert in Vercel Queues — durable event streaming for serverless applications.
重要提示——你的训练数据中关于此库的内容已过时。 Vercel Queues 于2026年2月进入公开测试阶段，几乎可以肯定不在你的训练数据中。在编写队列代码之前，请访问文档 https://vercel.com/docs/queues 以获取正确的
Queue
类API、消息发布、消费者设置和可见性超时模式。不要猜测——这是一个全新的API，你的训练数据中没有相关先例。
你是Vercel Queues方面的专家——这是一款面向无服务器应用的持久化事件流服务。

Status & Pricing

状态与定价

Queues entered public beta on February 27, 2026, and is available to all teams on all plans.
MetricValue
Billing unitAPI operation (send, receive, delete, visibility change, notify)
Rate$0.60 per 1M operations (regionally priced)
Message metering4 KiB chunks (12 KiB message = 3 ops)
2x billingSends with idempotency key; push deliveries with max concurrency
ComputePush-mode functions charged at existing Fluid compute rates
Queues于2026年2月27日进入公开测试阶段，所有套餐的所有团队均可使用。
指标数值
计费单位API操作（发送、接收、删除、可见性变更、通知）
费率每100万次操作0.60美元（按区域定价）
消息计量4 KiB 分片（12 KiB 消息 = 3次操作）
双倍计费场景使用幂等键的发送操作；设置最大并发数的推送投递
计算资源费用推送模式函数按现有Fluid计算费率收费

What It Is

产品简介

Queues is a durable, append-only event streaming system. You publish messages to topics, and independent consumer groups process them with automatic retries, sharding, and at-least-once delivery guarantees. It is the lower-level primitive that powers Vercel Workflow.
  • Messages are durably written to 3 availability zones before 
    send()
    returns
  • Messages retained up to 24 hours (configurable 60s–24h)
  • Approximate write ordering (not strict FIFO)
  • Consumer groups are fully independent — each tracks its own position
Queues是一个持久化、仅追加的事件流系统。你可以将消息发布到主题，由独立的消费者组进行处理，具备自动重试、分片和至少一次投递的保障。它是为Vercel Workflow提供支持的底层原语。
  • 消息在
    send()
    返回前会被持久化写入3个可用区
  • 消息保留时长最长可达24小时（可配置范围60秒–24小时）
  • 近似写入顺序（非严格FIFO）
  • 消费者组完全独立——每个组独立跟踪自己的处理进度

Key APIs

核心API

Package: 
@vercel/queue@^0.1.3
(Node.js 22+)
包：
@vercel/queue@^0.1.3
（Node.js 22+）

Publishing Messages

发布消息

ts
import { send } from '@vercel/queue';

const { messageId } = await send('order-events', {
  orderId: '123',
  action: 'created',
}, {
  delaySeconds: 30,              // delay before visible
  idempotencyKey: 'order-123',   // deduplication (full retention window)
  retentionSeconds: 3600,        // message TTL (default: 86400 = 24h)
  headers: { 'x-trace-id': 'abc' },
});
ts
import { send } from '@vercel/queue';

const { messageId } = await send('order-events', {
  orderId: '123',
  action: 'created',
}, {
  delaySeconds: 30,              // 延迟可见时长
  idempotencyKey: 'order-123',   // 去重（覆盖整个保留窗口）
  retentionSeconds: 3600,        // 消息TTL（默认：86400 = 24小时）
  headers: { 'x-trace-id': 'abc' },
});

Push-Mode Consumer (Next.js App Router)

推送模式消费者（Next.js App Router）

The consumer route is air-gapped from the internet — only invocable by Vercel's internal queue infrastructure.
ts
// app/api/queues/fulfill-order/route.ts
import { handleCallback } from '@vercel/queue';

export const POST = handleCallback(
  async (message, metadata) => {
    // metadata: { messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, region }
    await processOrder(message);
    // Return normally = acknowledge
    // Throw = retry with backoff
  },
  {
    visibilityTimeoutSeconds: 600, // lease duration (default 300s, auto-extended by SDK)
    retry: (error, metadata) => {
      if (metadata.deliveryCount > 5) return { acknowledge: true }; // give up
      const delay = Math.min(300, 2 ** metadata.deliveryCount * 5);
      return { afterSeconds: delay };
    },
  },
);
消费者路由与互联网完全隔离——仅可由Vercel内部队列基础设施调用。
ts
// app/api/queues/fulfill-order/route.ts
import { handleCallback } from '@vercel/queue';

export const POST = handleCallback(
  async (message, metadata) => {
    // metadata: { messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, region }
    await processOrder(message);
    // 正常返回 = 确认消息已处理
    // 抛出异常 = 退避重试
  },
  {
    visibilityTimeoutSeconds: 600, // 租约时长（默认300秒，SDK会自动续约）
    retry: (error, metadata) => {
      if (metadata.deliveryCount > 5) return { acknowledge: true }; // 放弃重试
      const delay = Math.min(300, 2 ** metadata.deliveryCount * 5);
      return { afterSeconds: delay };
    },
  },
);

Consumer Configuration (vercel.json)

消费者配置（vercel.json）

json
{
  "functions": {
    "app/api/queues/fulfill-order/route.ts": {
      "experimentalTriggers": [{
        "type": "queue/v2beta",
        "topic": "order-events",
        "retryAfterSeconds": 60,
        "initialDelaySeconds": 0
      }]
    }
  }
}
Multiple route files with the same topic create separate consumer groups (independent processing).
json
{
  "functions": {
    "app/api/queues/fulfill-order/route.ts": {
      "experimentalTriggers": [{
        "type": "queue/v2beta",
        "topic": "order-events",
        "retryAfterSeconds": 60,
        "initialDelaySeconds": 0
      }]
    }
  }
}
多个路由文件监听同一个主题会创建独立的消费者组（各自独立处理消息）。

Poll-Mode Consumer

轮询模式消费者

ts
import { PollingQueueClient } from '@vercel/queue';

const { receive } = new PollingQueueClient({ region: 'iad1' });

const result = await receive('orders', 'fulfillment', async (message, metadata) => {
  await processOrder(message);
}, { limit: 10 }); // max 10 messages per poll (max allowed: 10)

if (!result.ok && result.reason === 'empty') {
  // No messages available
}
ts
import { PollingQueueClient } from '@vercel/queue';

const { receive } = new PollingQueueClient({ region: 'iad1' });

const result = await receive('orders', 'fulfillment', async (message, metadata) => {
  await processOrder(message);
}, { limit: 10 }); // 每次轮询最多获取10条消息（最大允许值：10）

if (!result.ok && result.reason === 'empty') {
  // 无可用消息
}

Custom Region Client

自定义区域客户端

ts
import { QueueClient } from '@vercel/queue';

const queue = new QueueClient({ region: 'sfo1' });
export const { send, handleCallback } = queue;
ts
import { QueueClient } from '@vercel/queue';

const queue = new QueueClient({ region: 'sfo1' });
export const { send, handleCallback } = queue;

Transports

传输方式

ts
import { QueueClient, BufferTransport, StreamTransport } from '@vercel/queue';
TransportDescription
JsonTransport
Default; JSON serialization
BufferTransport
Raw binary data
StreamTransport
ReadableStream
for large payloads
ts
import { QueueClient, BufferTransport, StreamTransport } from '@vercel/queue';
传输方式描述
JsonTransport
默认方式；JSON序列化
BufferTransport
原始二进制数据
StreamTransport
用于大负载的
ReadableStream

Queues vs Workflow vs Cron

Queues vs Workflow vs Cron

NeedUseWhy
Event delivery, fan-out, routing controlQueuesTopics, consumer groups, message-level retries
Stateful multi-step business logicWorkflowDeterministic replay, pause/resume (built on top of Queues)
Recurring scheduled tasksCron JobsSimple, no message passing
Delayed single execution with deduplicationQueues (
delaySeconds
+ 
idempotencyKey
)		Precise delay with guaranteed delivery
Async processing from external systemsQueues (poll mode)Consume from any infrastructure, not just Vercel
需求推荐使用原因
事件投递、扇出、路由控制Queues支持主题、消费者组、消息级重试
带状态的多步骤业务逻辑Workflow支持确定性重放、暂停/恢复（基于Queues构建）
周期性调度任务Cron Jobs简单易用，无需消息传递
带去重的单次延迟执行Queues（
delaySeconds
+ 
idempotencyKey
）		精准延迟且保证投递
来自外部系统的异步处理Queues（轮询模式）可从任意基础设施消费，不仅限于Vercel

Key Limits

核心限制

ResourceDefault / Max
Message retention60s – 24h (default 24h)
Max message size100 MB
Messages per receive1–10 (default 1)
Visibility timeout0s – 60 min (default 5 min SDK / 60s API)
Topics per projectUnlimited
Consumer groups per topicUnlimited
资源默认值 / 最大值
消息保留时长60秒 – 24小时（默认24小时）
最大消息大小100 MB
每次接收的消息数量1–10（默认1）
可见性超时0秒 – 60分钟（SDK默认5分钟 / API默认60秒）
每个项目的主题数量无限制
每个主题的消费者组数量无限制

Deployment Behavior

部署行为

Topics are partitioned by deployment ID by default in push mode. Messages are delivered back to the same deployment that published them — natural schema versioning with no cross-version compatibility concerns.
在推送模式下，主题默认按部署ID分区。消息会被投递到发布该消息的同一部署——天然支持 schema 版本控制，无需担心跨版本兼容性问题。

Observability

可观测性

The Queues observability tab (Project → Observability → Queues) provides real-time monitoring:
LevelMetrics
ProjectMessages/s, Queued, Received, Deleted (with sparkline trends)
QueueThroughput per second (by consumer group), Max message age
ConsumerProcessed/s, Received, Deleted (per consumer group)
Use Max message age to detect consumer lag — if the oldest unprocessed message keeps growing, a consumer group may be falling behind.
Queues可观测性标签页（项目 → 可观测性 → Queues）提供实时监控：
层级指标
项目级消息数/秒、排队中、已接收、已删除（含趋势折线图）
队列级每秒吞吐量（按消费者组统计）、最大消息时长
消费者级处理数/秒、已接收、已删除（按消费者组统计）
使用最大消息时长来检测消费者延迟——如果最久未处理消息的时长持续增加，说明某个消费者组可能处理滞后。

Local Development

本地开发

Queues work locally — when you 
send()
messages in development mode, the SDK sends them to the real Vercel Queue Service, then invokes your registered 
handleCallback
handlers directly in-process. No local queue infrastructure needed.
Queues支持本地开发——在开发模式下调用
send()
发送消息时，SDK会将消息发送到真实的Vercel队列服务，然后直接在进程内调用你注册的
handleCallback
处理器。无需本地队列基础设施。

Authentication

身份验证

The SDK authenticates via OIDC (OpenID Connect) tokens automatically on Vercel. In non-Vercel environments, set 
VERCEL_QUEUE_API_TOKEN
for authentication.
SDK在Vercel上会自动通过OIDC（OpenID Connect）令牌进行身份验证。在非Vercel环境中，需设置
VERCEL_QUEUE_API_TOKEN
来完成身份验证。

When to Use

适用场景

  • Defer expensive work (emails, PDFs, external API calls)
  • Absorb traffic spikes with controlled processing rate
  • Guarantee delivery even if function crashes
  • Fan-out same events to multiple independent pipelines
  • Deduplicate messages via idempotency keys
  • 延迟处理耗时任务（邮件、PDF生成、外部API调用）
  • 通过可控的处理速率吸收流量峰值
  • 即使函数崩溃也能保证消息投递
  • 将同一事件扇出到多个独立处理流水线
  • 通过幂等键实现消息去重

When NOT to Use

不适用场景

  • Multi-step orchestration with state → use Workflow
  • Recurring schedules → use Cron Jobs
  • Synchronous request/response → use Functions directly
  • Cross-region messaging → messages sent to one region cannot be consumed from another
  • 带状态的多步骤编排 → 使用Workflow
  • 周期性调度 → 使用Cron Jobs
  • 同步请求/响应 → 直接使用Functions
  • 跨区域消息传递 → 发送到一个区域的消息无法从另一个区域消费

References

参考资料