# @azure/storage-queue 中文文档

规范地址：https://npmcn.com/package/%40azure/storage-queue/

版本：12\.32\.0
npm 元数据更新时间：2026-09-24T12:50:56.285Z
中文译文更新时间：2026-11-07T13:15:07.646Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/storage-queue
原文对照：https://npmcn.com/package/%40azure/storage-queue/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/storage/storage-queue/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.3 MB，632 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：13 个
- 首次发布：2018-12-12T23:32:50.636Z
- 最新版本发布：2026-09-24T12:50:55.795Z
- 近 30 天下载量：2893236（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：509（近 12 个月 51 个）

## 中文简介

Microsoft Azure 存储 JavaScript - 队列

## 安装

```sh
npm install @azure/storage-queue
```

也可以使用：`pnpm add @azure/storage-queue`、`yarn add @azure/storage-queue`、`bun add @azure/storage-queue`

## README

# 用于 JavaScript 的 Azure 存储队列客户端库

Azure存储队列在应用程序组件之间提供云信息. 在为规模设计应用程序时,应用程序组件往往被去钩,以便它们能够独立地进行规模化. 队列存储为应用程序组件之间的通信提供同步消息,无论是在云中运行,还是在桌面上运行,还是在一个premies服务器上运行,还是在移动设备上运行. 队列存储还支持管理同步任务并构建进程工作流程.

这个工程在JavaScript中提供了一个客户端库,使得它更容易地消费Azure存储队列服务.

使用此软件包中的客户端库 :

-   获取/设置队列服务属性
-   创建/列表/删除队列
-   发送/接收/Peek/ Clear/Update/删除队列信件

密钥链接 :

-   [源代码](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/storage/storage-queue)
-   [软件包( npm)](https://www.npmjs.com/package/@azure/storage-queue)
-   [API 参考文档](https://learn.microsoft.com/javascript/api/@azure/storage-queue)
-   [产品文档](https://learn.microsoft.com/azure/storage/queues/storage-queues-introduction)
-   [样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/storage/storage-queue/samples)
-   [Azure 存储队列 REST APIs](https://learn.microsoft.com/rest/api/storageservices/queue-service-rest-api)

## 开始

### 目前得到支持的环境

-   [节点.js的LTS版本](https://github.com/nodejs/release#release-schedule)
-   Safari,Chrome,Edge,和Firefox的最新版本.

看我们的 [支助政策](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md) 更多细节.

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/free/)
-   A 类 [存储账户](https://learn.microsoft.com/azure/storage/common/storage-account-create)

### 安装软件包

为 JavaScript 安装 Azure 存储队列客户端库的首选方法是使用 npm 包管理器. 键入下列终端窗口:

```bash
npm install @azure/storage-queue
```

### 认证客户端

Azure存储器支持几种认证方法. 为了与 Azure Quee 存储服务互动, 您需要创建存储客户端实例 `QueueServiceClient` 或者说 `QueueClient` 举个例子 见 [用于创建 `QueueServiceClient`](https://npmcn.com/package/%40azure/storage-queue/#readme-create-the-queue-service-client) 学习更多关于认证.

-   [Azure 活动目录](https://npmcn.com/package/%40azure/storage-queue/#readme-with-defaultazurecredential-from-azureidentity-package)
-   [共享密钥](https://npmcn.com/package/%40azure/storage-queue/#readme-with-storagesharedkeycredential)
-   [共享访问签名](https://npmcn.com/package/%40azure/storage-queue/#readme-with-sas-token)

#### Azure 活动目录

Azure Quee存储服务支持使用 Azure Active Directory来认证请求到它的API. 这个 [`@azure/identity`](https://www.npmjs.com/package/@azure/identity) 软件包提供了各种证书类型,应用程序可用来做到这一点。 请看 [读取 `@azure/identity`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity/README.md) 需要更多的细节和样本来启动.

### 兼容性

这个库与Node.js和浏览器兼容,并与LTS Node.js版本(QQ8.16.0)和Chrome,Firefox和Edge等最新版本进行验证.

#### 网络工人

这个库要求某些DOM对象在浏览器中使用时可以全局取用,而网页工人默认不会提供. 您需要多填这些, 才能让这个图书馆在网络工作人员中工作 .

详情请参见我们 [在网络工人中使用Azure SDK的文档](https://aka.ms/azsdk/js/web-workers)

此库依赖于在网络工人使用时需要加载外部多填充的 DOM API :

-   [`document`](https://developer.mozilla.org/docs/Web/API/Document)
-   [`DOMParser`](https://developer.mozilla.org/docs/Web/API/DOMParser)
-   [`Node`](https://developer.mozilla.org/docs/Web/API/Node)
-   [`XMLSerializer`](https://developer.mozilla.org/docs/Web/API/XMLSerializer)

#### 节点J和浏览器之间的差异

节点(Node.js)和浏览器运行时间有差异. 启动此库时, 请注意 API 或 标有 _"绝对是无处可逃"_ 或者说 _"绝对是活在丛生"_。 。 。 .

##### 以下特性,界面,类或函数仅在Node.js中提供

-   基于账户名称和账户密钥的共享密钥授权
    -   `StorageSharedKeyCredential`
-   共享访问签名( SAS) 生成
    -   `generateAccountSASQueryParameters()`
    -   `generateQueueSASQueryParameters()`

### Java 脚本套装

要在浏览器中使用此客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 [捆绑文件](https://aka.ms/AzureSDKBundling)。 。 。 .

### (简体中文)

你需要设置 [跨欧林资源共享](https://learn.microsoft.com/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services) 用于浏览器的存储账户规则。 到 Azure 门户网站和 Azure 存储探索器, 找到您的存储账户, 为 blob/ queue/ file/ table 服务创建新的 CORS 规则 .

例如,您可以按照 CORS 设置创建调试程序。 但请根据生产环境的要求,精心定制设置.

-   允许来源: \*
-   允许动词: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
-   允许的标题 : \*
-   已曝光标题 : \*
-   最大年龄(秒):86400

## 关键概念

A 队列是 Azure 存储队列服务账户内发送/接收信件的数据存储器 连接客户端之间.

我们图书馆中与这些服务有关的关键数据类型是:

-   A 类 `QueueServiceClient` 代表连接( 通过 URL) 给定 _存储账户_ 在Azure存储队列服务中,并提供API来操纵其队列. 它被认证为服务,可用于创建 `QueueClient` 对象,以及创建、删除、列出服务中的队列.
-   A 类 `QueueClient` 代表单人 _队列_ 在存储账户。 它可用于操纵队列中的信息,例如发送,接收,并偷看队列中的信息.

## 实例

### 导入软件包

要使用客户端, 请导入软件包到您的文件中 :

```ts
import * as AzureStorageQueue from "@azure/storage-queue";
```

或者,有选择地仅导入所需的类型:

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

### 创建队列服务客户端

这个 `QueueServiceClient` 需要队列服务的 URL 和访问证书 。 也可以选择接受 `options` 参数.

#### 与 `DefaultAzureCredential` 从 `@azure/identity` 软件包

**建议的即兴演奏方式a `QueueServiceClient`**

设置 : 引用 - 授权使用 Azure Active 目录从客户端应用程序访问 blobs 和队列 - [https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app 互联网档案馆的存檔,存档日期2013-12-22](https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app)

-   注册新的 AAD 应用程序, 并允许代表登录用户访问 Azure 存储器
    
    -   在 Azure 活动目录( azure-portal) 中注册新的应用程序 - [https://learn.microsoft.com/azure/活出-指导/develop/quickstart-register-app. 互联网档案馆的存檔,存档日期2013-12-21](https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app)
    -   在那个 `API permissions` 区域,选择 `Add a permission` 选择 `Microsoft APIs`。 。 。 .
    -   选择 `Azure Storage` 并选择旁边的复选框 `user_impersonation` 然后单击 `Add permissions`。这将使应用程序能够代表登录用户访问Azure存储器.
-   允许在Azure门户网站上访问RBAC的Azure存储队列数据
    
    -   空管局在排队和排队上的角色 [https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal 互联网档案馆的存檔,存档日期2013-12-21](https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal)。 。 。 .
    -   在Azure门户网站,去你的存储账户 并分配 **存储队列数据贡献器** 角色到注册的 AAD 应用程序 `Access control (IAM)` 选项卡(在azure-portal中您存储账户的左侧导航栏).
-   样本的环境设置
    
    -   从您的 AAD 应用程序的概览页面中,请注意 `CLIENT ID` 财务报告和审定财务报表 `TENANT ID`。在“证书和机密”标签中,创建一个机密,并将此记下.
    -   确保你有 `AZURE_TENANT_ID`, (中文(简体) ), `AZURE_CLIENT_ID`, (中文(简体) ), `AZURE_CLIENT_SECRET` 作为成功执行样本的环境变量(can liberation process.env.).

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

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential,
);
```

\[注 -- -- 以上步骤只针对节点.js\]

#### 使用连接字符串

或者,你可以即时 `QueueServiceClient` 使用 `fromConnectionString()` 以全连接字符串作为参数的静态方法。 (连接字符串可以从Azure门户网站获得. \[完全可以在 代码.Js运行\]

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

const connectionString = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);
```

#### 与 `StorageSharedKeyCredential`

或者,你即兴表演 `QueueServiceClient` 带有 `StorageSharedKeyCredential` 路过 `accountName` 财务报告和审定财务报表 `accountKey` 作为论据。 (账户名和账户密钥的值可以从Azure门户网站获得. ) \[完全可以在 代码.JS运行\]

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

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    userAgentOptions: {
      userAgentPrefix: "BasicSample V10.0.0",
    }, // Customized telemetry string
  },
);
```

#### 与 SAS Token 连接

还有... 你可以即兴表演 `QueueServiceClient` 带有共享访问签名(SAS). 您可以从 Azure 端口获得 SAS 令牌或使用 `generateAccountSASQueryParameters()`。 。 。 .

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

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net?${sas}`,
);
```

### 在此账户中列出队列

使用 `QueueServiceClient.listQueues()` 函数以排列队列, 与新的 `for-await-of` 语法 :

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const item of queueServiceClient.listQueues()) {
  console.log(`Queue${i++}: ${item.name}`);
}
```

或者没有 `for-await-of`数字 :

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iterator = queueServiceClient.listQueues();
let { done, value } = await iterator.next();
while (!done) {
  console.log(`Queue${i++}: ${value.name}`);
  ({ done, value } = await iterator.next());
}
```

列行列上的完整样本请参见 [样本/v12/类型标记/列表](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/storage/storage-queue/samples/v12/typescript/src/listQueues.ts)。 。 。 .

### 创建新队列

使用 `QueueServiceClient.getQueueClient()` 函数以创建新队列.

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const createQueueResponse = await queueClient.create();
console.log(
  `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`,
);
```

### 向队列发送消息

使用 `sendMessage()` 在队列中添加消息 :

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
// Send a message into the queue using the sendMessage method.
const sendMessageResponse = await queueClient.sendMessage("Hello World!");
console.log(
  `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`,
);
```

### 皮克一个消息

`QueueClient.peekMessages()` 允许在队列前查看一个或多个消息。 这个电话 并不妨碍其他代码访问被偷看的消息.

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const peekMessagesResponse = await queueClient.peekMessages();
console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
```

### 处理信件

消息分两步处理.

-   第一通电话 `queueClient.receiveMessages()`。这使该队列中发来的其他代码读取信件隐形,默认时间为30秒.
-   处理信件时,请拨 `queueClient.deleteMessage()` 带消息的 `popReceipt`。 。 。 .

如果由于硬件或软件故障,您的代码无法处理一个消息,这个双步进程可以确保您代码中的另一个实例可以得到相同的消息并再次尝试.

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const response = await queueClient.receiveMessages();
if (response.receivedMessageItems.length === 1) {
  const receivedMessageItem = response.receivedMessageItems[0];
  console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
  const deleteMessageResponse = await queueClient.deleteMessage(
    receivedMessageItem.messageId,
    receivedMessageItem.popReceipt,
  );
  console.log(
    `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`,
  );
}
```

### 删除队列

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

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const deleteQueueResponse = await queueClient.delete();
console.log(
  `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`,
);
```

简单的完整实例 `QueueServiceClient` 假设值为 [样本/v12/型号标注/弧度/克克克特.ts](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/storage/storage-queue/samples/v12/typescript/src/queueClient.ts)。 。 。 .

## 解决问题

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 `AZURE_LOG_LEVEL` 环境变量改为 `info`。或者,可以在运行时拨打 `setLogLevel` 输入 `@azure/logger`数字 :

```ts
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```

## 今后的步骤

更多代码样本

-   [队列存储样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/storage/storage-queue/samples)
-   [队列存储测试例](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/storage/storage-queue/test)

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) 学习如何构建和测试密码.

另见 [存储特定指南](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/storage/CONTRIBUTING.md) 关于为存储库设置测试环境的更多信息.

## 常见问题

### @azure/storage-queue 是什么？

Microsoft Azure 存储 JavaScript - 队列

### 如何安装 @azure/storage-queue？

在项目目录运行 npm install @azure/storage-queue，或使用 pnpm add / yarn add / bun add。

### @azure/storage-queue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/storage-queue 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/storage-queue 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/storage-queue 可以商用吗？

@azure/storage-queue 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/storage-queue 的下载量有多少？

根据 npm 官方下载统计，@azure/storage-queue 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,893,236 次，日均约 96,441 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/storage-queue 还在维护吗？

最新版本 12\.32\.0 发布于 2026/09/24（1 个月前）；至今共发布 509 个版本，其中过去 12 个月发布了 51 个；首次发布于 2018/12/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。