---

name: azure-storage-queue-ts description: Azure Queue Storage JavaScript/TypeScript SDK (@azure/storage-queue) 消息队列操作。用于发送、接收、查看和删除队列中的消息。 risk: unknown source: community date_added: '2026-02-27'

@azure/storage-queue (TypeScript/JavaScript)

用于 Azure Queue Storage 操作的 SDK——发送、接收、查看和管理队列中的消息。

安装

npm install @azure/storage-queue @azure/identity

当前版本：12.x
Node.js：>= 18.0.0

环境变量

AZURE_STORAGE_ACCOUNT_NAME=<account-name>
AZURE_STORAGE_ACCOUNT_KEY=<account-key>
# 或连接字符串
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...

认证

DefaultAzureCredential（推荐）

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const client = new QueueServiceClient(
  `https://${accountName}.queue.core.windows.net`,
  new DefaultAzureCredential()
);

连接字符串

import { QueueServiceClient } from "@azure/storage-queue";

const client = QueueServiceClient.fromConnectionString(
  process.env.AZURE_STORAGE_CONNECTION_STRING!
);

StorageSharedKeyCredential（仅 Node.js）

import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY!;

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
const client = new QueueServiceClient(
  `https://${accountName}.queue.core.windows.net`,
  sharedKeyCredential
);

SAS 令牌

import { QueueServiceClient } from "@azure/storage-queue";

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN!;

const client = new QueueServiceClient(
  `https://${accountName}.queue.core.windows.net${sasToken}`
);

客户端层级

QueueServiceClient（账户级别）
└── QueueClient（队列级别）
    └── Messages（发送、接收、查看、删除）

队列操作

创建队列

const queueClient = client.getQueueClient("my-queue");
await queueClient.create();

// 或不存在时创建
await queueClient.createIfNotExists();

列出队列

for await (const queue of client.listQueues()) {
  console.log(queue.name);
}

// 使用前缀过滤
for await (const queue of client.listQueues({ prefix: "task-" })) {
  console.log(queue.name);
}

删除队列

await queueClient.delete();

// 或存在时删除
await queueClient.deleteIfExists();

获取队列属性

const properties = await queueClient.getProperties();
console.log("大约消息数量:", properties.approximateMessagesCount);

消息操作

发送消息

// 简单文本消息
await queueClient.sendMessage("Hello, Queue!");

// 带选项的消息
await queueClient.sendMessage(
  Buffer.from(JSON.stringify({ task: "process", id: 123 })).toString("base64"),
  {
    visibilityTimeout: 30, // 30 秒内对其他消费者不可见
    messageTimeToLive: 3600, // 1 小时后过期
  }
);

接收消息

// 接收并处理消息（使其对其他消费者不可见）
const response = await queueClient.receiveMessages({
  numberOfMessages: 5, // 最多 32 条
  visibilityTimeout: 30, // 处理时间（秒）
});

for (const message of response.receivedMessageItems) {
  console.log("消息:", message.messageText);
  console.log("ID:", message.messageId);
  console.log("出队次数:", message.dequeueCount);

  // 处理后删除
  await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

查看消息

// 查看但不移除消息（不影响可见性）
const peeked = await queueClient.peekMessages({ numberOfMessages: 5 });

for (const message of peeked.peekedMessageItems) {
  console.log("查看:", message.messageText);
}

更新消息

// 更新消息内容和可见性超时
const received = await queueClient.receiveMessages();
const msg = received.receivedMessageItems[0];

await queueClient.updateMessage(
  msg.messageId,
  msg.popReceipt,
  "更新后的内容",
  60 // 新的可见性超时（秒）
);

清空队列

await queueClient.clearMessages();