使用 @azure/storage-blob TypeScript SDK 管理 Azure Blob Storage:AAS 云基础设施技能实战指南
使用 @azure/storage-blob TypeScript SDK 管理 Azure Blob Storage:AAS 云基础设施技能实战指南
导读
本文以开源仓库 agentic-awesome-skills 中收录的 azure-storage-blob-ts 技能文档(plugins/agentic-awesome-skills-claude/skills/azure-storage-blob-ts/SKILL.md)为主体,系统讲解使用 TypeScript/JavaScript 官方 SDK(@azure/storage-blob)完成 Blob 与容器的上传、下载、列举、复制、SAS 令牌签发等全部核心操作。读完本文,你将掌握四种认证方式的取舍、客户端三级对象模型、三种 Blob 类型(Block/Append/Page)的适用场景,以及一套可直接落地的错误处理与安全最佳实践,可将其作为在 Node.js 与浏览器双端进行 Azure 对象存储开发的速查手册。
技能定位与仓库元数据
azure-storage-blob-ts 是 AAS(Agentic Awesome Skills)社区技能库中一枚面向 Azure 云存储基础设施操作 的 TypeScript 技能。仓库的数据索引 data/catalog.json(第 10533–10561 行)与 skills_index.json(第 8678–8699 行)记录了它的完整元数据:
- 分类:
cloud - 风险等级:
critical—— 从 docs/sources/sources.md 对同类基础设施批次的说明可以看出,凡是会直接变更云基础设施状态(创建、删除、复制对象)的指导类技能均被标记为critical; - 来源:
community,由社区基础设施批次导入; - 触发词:
azure、storage、blob、ts、uploading、downloading、listing、managing等,供 Agent 在遇到对应任务时自动路由到该技能。
该技能在 AAS 插件体系中同时面向 Codex 与 Claude 两个目标平台(见 skills_index.json 中的 plugin.targets),且 setup.type 为 none,即不需要额外安装脚本,仅需在项目内安装 npm 依赖即可使用。
安装与环境准备
技能文档要求的安装方式极为简洁,一条命令同时引入存储 SDK 与 Azure 身份认证库:
npm install @azure/storage-blob @azure/identity
运行前提(以文档声明为准):
- 当前版本线:
@azure/storage-blob12.x; - Node.js:>= 18.0.0(
@azure/identity与部分 Node 专属 API 依赖该版本之上的运行时特性)。
Blob 账户信息通过环境变量注入,避免在代码中硬编码凭据:
AZURE_STORAGE_ACCOUNT_NAME=<account-name>
AZURE_STORAGE_ACCOUNT_KEY=<account-key>
# OR connection string
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
其中连接字符串(connection string)包含完整的账户端点与密钥信息,格式为 DefaultEndpointsProtocol=https;AccountName=<name>;AccountKey=<key>;EndpointSuffix=core.windows.net,使用 .env 文件配合 dotenv 加载即可在本地开发时保持整洁。
认证:四种方式与选择依据
SDK 支持四种主流认证路径,技能文档按推荐优先级排列。
1. DefaultAzureCredential(推荐)
DefaultAzureCredential 来自 @azure/identity,会按固定顺序尝试环境变量、Azure CLI 登录态、托管身份等来源,自动完成 AAD(Microsoft Entra ID)认证,无需管理密钥:
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const client = new BlobServiceClient(
`https://${accountName}.blob.core.windows.net`,
new DefaultAzureCredential()
);
它是本地开发、CI/CD(工作负载身份)与生产环境(托管身份)之间的统一选择,也是技能文档“最佳实践”第一条的推荐方案。
2. 连接字符串
适合快速原型与脚本场景,一行代码即可创建客户端:
import { BlobServiceClient } from "@azure/storage-blob";
const client = BlobServiceClient.fromConnectionString(
process.env.AZURE_STORAGE_CONNECTION_STRING!
);
3. StorageSharedKeyCredential(仅 Node.js)
使用账户名 + 账户密钥,由 SDK 内部完成 HMAC-SHA256 签名:
import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";
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 BlobServiceClient(
`https://${accountName}.blob.core.windows.net`,
sharedKeyCredential
);
4. SAS Token
适用于需要将受限访问权委托给第三方的场景。令牌以 ? 开头拼接在端点后:
import { BlobServiceClient } from "@azure/storage-blob";
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN!; // starts with "?"
const client = new BlobServiceClient(
`https://${accountName}.blob.core.windows.net${sasToken}`
);
四种方式的取舍可归纳为:优先 AAD 托管身份(DefaultAzureCredential),短期委托用 SAS,脚本原型可用连接字符串,Node 服务端内部集成才考虑共享密钥。
客户端对象模型:三级层级结构
SDK 以“服务 → 容器 → Blob”三级对象模型组织,技能文档用如下树形结构清晰表达:
BlobServiceClient (account level)
└── ContainerClient (container level)
└── BlobClient (blob level)
├── BlockBlobClient (block blobs - most common)
├── AppendBlobClient (append-only blobs)
└── PageBlobClient (page blobs - VHDs)
- BlobServiceClient:账户级入口,负责列举/管理容器、签发账户级 SAS;
- ContainerClient:容器级操作(创建、删除、列举 Blob);
- BlobClient / BlockBlobClient / AppendBlobClient / PageBlobClient:对象级操作,其中
BlockBlobClient覆盖了绝大多数文本与二进制文件场景。
每个下级客户端都通过上级客户端的 get*Client 工厂方法获得,例如 client.getContainerClient("my-container") 与 containerClient.getBlockBlobClient("my-file.txt")。
容器操作:创建、列举与删除
创建容器
const containerClient = client.getContainerClient("my-container");
await containerClient.create();
// Or create if not exists
await containerClient.createIfNotExists();
createIfNotExists() 返回幂等结果,适合重复运行的任务脚本——这也是技能“最佳实践”第 6 条强调 *IfNotExists 方法的原因:避免容器已存在时抛出 409 冲突错误。
列举容器
// 全量列举
for await (const container of client.listContainers()) {
console.log(container.name);
}
// 按前缀过滤
for await (const container of client.listContainers({ prefix: "logs-" })) {
console.log(container.name);
}
listContainers 返回异步迭代器,prefix 选项可按命名前缀(如 logs-)缩小枚举范围,适合按环境或业务域划分容器的场景。
删除容器
await containerClient.delete();
// Or delete if exists
await containerClient.deleteIfExists();
删除容器是不可逆操作,deleteIfExists() 同样提供幂等语义。
Blob 操作:上传、下载、列举与复制
上传:四种方式覆盖 Node 与浏览器
(1)简单上传(字符串 / Buffer)
const containerClient = client.getContainerClient("my-container");
const blockBlobClient = containerClient.getBlockBlobClient("my-file.txt");
// Upload string
await blockBlobClient.upload("Hello, World!", 13);
// Upload Buffer
const buffer = Buffer.from("Hello, World!");
await blockBlobClient.upload(buffer, buffer.length);
upload() 的第二个参数为字节长度,必须与实际内容长度一致。
(2)从文件上传(Node.js 专属)
const blockBlobClient = containerClient.getBlockBlobClient("uploaded-file.txt");
await blockBlobClient.uploadFile("/path/to/local/file.txt");
(3)从流上传(Node.js 专属,大文件首选)
import * as fs from "fs";
const blockBlobClient = containerClient.getBlockBlobClient("streamed-file.txt");
const readStream = fs.createReadStream("/path/to/local/file.txt");
await blockBlobClient.uploadStream(readStream, 4 * 1024 * 1024, 5, {
// bufferSize: 4MB, maxConcurrency: 5
onProgress: (progress) => console.log(`Uploaded ${progress.loadedBytes} bytes`),
});
uploadStream 的参数语义为 (stream, bufferSize, maxConcurrency, options):bufferSize 决定每个上传块的大小(示例为 4MB),maxConcurrency 控制并发块数(示例为 5),并可通过 onProgress 回调实时获取 loadedBytes 进度。技能“最佳实践”第 2 条明确:大于 256MB 的文件应使用流式上传,以控制内存占用并利用并发提升吞吐。
(4)从浏览器上传
const blockBlobClient = containerClient.getBlockBlobClient("browser-upload.txt");
// From File input
const fileInput = document.getElementById("fileInput") as HTMLInputElement;
const file = fileInput.files![0];
await blockBlobClient.uploadData(file);
// From Blob/ArrayBuffer
const arrayBuffer = new ArrayBuffer(1024);
await blockBlobClient.uploadData(arrayBuffer);
uploadData 是浏览器端的通用入口,直接接受 File、Blob 或 ArrayBuffer。
下载:字符串、文件与 Buffer
(1)下载为字符串(跨平台)
const blobClient = containerClient.getBlobClient("my-file.txt");
const downloadResponse = await blobClient.download();
// Read as string (browser & Node.js)
const downloaded = await streamToText(downloadResponse.readableStreamBody!);
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
const chunks: Buffer[] = [];
for await (const chunk of readable) {
chunks.push(Buffer.from(chunk));
}
return Buffer.concat(chunks).toString("utf-8");
}
download() 返回的可读流 readableStreamBody 需要手动消费,streamToText 是文档提供的标准聚合工具函数。
(2)下载到文件(Node.js 专属)
const blockBlobClient = containerClient.getBlockBlobClient("my-file.txt");
await blockBlobClient.downloadToFile("/path/to/local/destination.txt");
(3)下载到 Buffer(Node.js 专属)
const blockBlobClient = containerClient.getBlockBlobClient("my-file.txt");
const buffer = await blockBlobClient.downloadToBuffer();
console.log(buffer.toString());
对于大文件,downloadToFile 与 downloadToBuffer 采用分块拉取,配合技能文档中 uploadStream 的最佳实践构成完整的大文件双端管线。
列举 Blob:扁平、前缀与层级
// 扁平列举全部 Blob
for await (const blob of containerClient.listBlobsFlat()) {
console.log(blob.name, blob.properties.contentLength);
}
// 按前缀过滤
for await (const blob of containerClient.listBlobsFlat({ prefix: "logs/" })) {
console.log(blob.name);
}
// 按层级列举(模拟虚拟目录)
for await (const item of containerClient.listBlobsByHierarchy("/")) {
if (item.kind === "prefix") {
console.log(`Directory: ${item.name}`);
} else {
console.log(`Blob: ${item.name}`);
}
}
listBlobsFlat:扁平列举,可通过prefix模拟目录筛选;listBlobsByHierarchy:按分隔符(如/)聚合出虚拟目录结构,item.kind为prefix表示目录节点,否则为 Blob 节点——适合需要渲染树形目录界面的场景。
删除 Blob
const blobClient = containerClient.getBlobClient("my-file.txt");
await blobClient.delete();
// Delete if exists
await blobClient.deleteIfExists();
// Delete with snapshots
await blobClient.delete({ deleteSnapshots: "include" });
deleteSnapshots: "include" 会在删除 Blob 时一并清除其全部快照,避免残留。
复制 Blob(异步 Copy)
const sourceBlobClient = containerClient.getBlobClient("source.txt");
const destBlobClient = containerClient.getBlobClient("destination.txt");
// Start copy operation
const copyPoller = await destBlobClient.beginCopyFromURL(sourceBlobClient.url);
await copyPoller.pollUntilDone();
beginCopyFromURL 发起异步服务端复制,返回轮询器(poller),pollUntilDone() 阻塞直至复制完成;大对象的复制是服务端执行的,不占用客户端带宽。
Blob 属性与元数据管理
获取属性
const blobClient = containerClient.getBlobClient("my-file.txt");
const properties = await blobClient.getProperties();
console.log("Content-Type:", properties.contentType);
console.log("Content-Length:", properties.contentLength);
console.log("Last Modified:", properties.lastModified);
console.log("ETag:", properties.etag);
getProperties 返回的对象包含 MIME 类型、字节长度、最后修改时间与 ETag(可用于并发校验与缓存)。
设置元数据
await blobClient.setMetadata({
author: "John Doe",
category: "documents",
});
元数据以键值对形式附着在 Blob 上,适合存放作者、分类等业务标签。
设置 HTTP 头
await blobClient.setHTTPHeaders({
blobContentType: "text/plain",
blobCacheControl: "max-age=3600",
blobContentDisposition: "attachment; filename=download.txt",
});
正确的 blobContentType(MIME)对浏览器直接访问与 CDN 缓存至关重要;blobContentDisposition 可强制浏览器以下载方式处理而非内联打开——这正是技能“最佳实践”第 3 条“为 Blob 设置正确内容类型”的具体落点。
SAS 令牌生成(Node.js 专属)
SAS(Shared Access Signature)是向浏览器/第三方授予限定权限、限定有效期访问权的最安全方式。技能文档给出了三级 SAS 的完整示例。
Blob 级 SAS(只读,1 小时)
import {
BlobSASPermissions,
generateBlobSASQueryParameters,
StorageSharedKeyCredential,
} from "@azure/storage-blob";
const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
const sasToken = generateBlobSASQueryParameters(
{
containerName: "my-container",
blobName: "my-file.txt",
permissions: BlobSASPermissions.parse("r"), // read only
startsOn: new Date(),
expiresOn: new Date(Date.now() + 3600 * 1000), // 1 hour
},
sharedKeyCredential
).toString();
const sasUrl = `https://${accountName}.blob.core.windows.net/my-container/my-file.txt?${sasToken}`;
BlobSASPermissions.parse("r") 表示只读(read);startsOn 与 expiresOn 控制令牌生效与失效时间。
容器级 SAS(读写删列,24 小时)
import { ContainerSASPermissions, generateBlobSASQueryParameters } from "@azure/storage-blob";
const sasToken = generateBlobSASQueryParameters(
{
containerName: "my-container",
permissions: ContainerSASPermissions.parse("racwdl"), // read, add, create, write, delete, list
expiresOn: new Date(Date.now() + 24 * 3600 * 1000), // 24 hours
},
sharedKeyCredential
).toString();
容器级权限字符依次对应 read(读)、add(添加)、create(创建)、write(写)、delete(删除)、list(列举)。
账户级 SAS(全权限,24 小时)
import {
AccountSASPermissions,
AccountSASResourceTypes,
AccountSASServices,
generateAccountSASQueryParameters,
} from "@azure/storage-blob";
const sasToken = generateAccountSASQueryParameters(
{
services: AccountSASServices.parse("b").toString(), // blob
resourceTypes: AccountSASResourceTypes.parse("sco").toString(), // service, container, object
permissions: AccountSASPermissions.parse("rwdlacupi"), // all permissions
expiresOn: new Date(Date.now() + 24 * 3600 * 1000),
},
sharedKeyCredential
).toString();
账户级 SAS 需要同时声明服务(b = blob)、资源类型(s = service、c = container、o = object)与权限集合,粒度最粗,应谨慎使用并尽量缩短有效期。
安全要点:所有 SAS 生成均依赖 StorageSharedKeyCredential,因此只在服务端(Node.js)签发;浏览器端只消费签好的短时效令牌——这与“最佳实践”第 4 条“用 SAS 令牌服务客户端访问”完全对应。
三种 Blob 类型与适用场景
| 类型 | 客户端 | 特点 | 典型场景 |
|---|---|---|---|
| Block Blob | BlockBlobClient |
默认类型,按块上传、支持并行与断点续传 | 文本、图片、PDF、视频等常规文件 |
| Append Blob | AppendBlobClient |
只允许追加写入,块大小固定 | 日志、审计追踪、监控数据流 |
| Page Blob | PageBlobClient |
512 字节对齐的随机读写 | VHD 虚拟磁盘、数据库文件 |
Block Blob(默认)
const blockBlobClient = containerClient.getBlockBlobClient("document.pdf");
await blockBlobClient.uploadFile("/path/to/document.pdf");
Append Blob(追加型)
const appendBlobClient = containerClient.getAppendBlobClient("app.log");
// Create the append blob
await appendBlobClient.create();
// Append data
await appendBlobClient.appendBlock("Log entry 1\n", 12);
await appendBlobClient.appendBlock("Log entry 2\n", 12);
appendBlock 的第二个参数为本次追加块的字节长度,与 upload 的语义一致;由于只能追加、不能改写已有内容,天然适合日志与审计场景。
Page Blob(页型)
const pageBlobClient = containerClient.getPageBlobClient("disk.vhd");
// Create 512-byte aligned page blob
await pageBlobClient.create(1024 * 1024); // 1MB
// Write pages (must be 512-byte aligned)
const buffer = Buffer.alloc(512);
await pageBlobClient.uploadPages(buffer, 0, 512);
页 Blob 创建时必须指定大小,且所有写入必须按 512 字节对齐——这是 VHD 类随机读写负载的硬性约束。
错误处理:基于 RestError 的分支
@azure/storage-blob 的网络/存储错误统一封装为 RestError,技能文档给出了按 statusCode 分类处理的完整范式:
import { RestError } from "@azure/storage-blob";
try {
await containerClient.create();
} catch (error) {
if (error instanceof RestError) {
switch (error.statusCode) {
case 404:
console.log("Container not found");
break;
case 409:
console.log("Container already exists");
break;
case 403:
console.log("Access denied");
break;
default:
console.error(`Storage error ${error.statusCode}: ${error.message}`);
}
}
throw error;
}
三个高频状态码的含义:
- 404:资源不存在(容器/Blob 未找到或已删除);
- 409:冲突(容器已存在、Blob 正被租约锁定等);
- 403:访问被拒(认证失败、SAS 过期或权限不足)。
注意 throw error 保留了异常向上传递的能力,避免吞掉未识别错误——这是“最佳实践”第 5 条“优雅处理错误”的完整实现。
TypeScript 类型速查
技能文档为读者整理了一份可直接导入的类型清单,覆盖客户端、认证、SAS、响应与错误五大类:
import {
// Clients
BlobServiceClient,
ContainerClient,
BlobClient,
BlockBlobClient,
AppendBlobClient,
PageBlobClient,
// Authentication
StorageSharedKeyCredential,
AnonymousCredential,
// SAS
BlobSASPermissions,
ContainerSASPermissions,
AccountSASPermissions,
AccountSASServices,
AccountSASResourceTypes,
generateBlobSASQueryParameters,
generateAccountSASQueryParameters,
// Options & Responses
BlobDownloadResponseParsed,
BlobUploadCommonResponse,
ContainerCreateResponse,
BlobItem,
ContainerItem,
// Errors
RestError,
} from "@azure/storage-blob";
其中 AnonymousCredential 用于显式声明匿名(公共容器)访问;BlobDownloadResponseParsed 等 *Response 类型对应各操作方法的解析结果,可用于编写类型安全的封装层。
平台差异对照表
SDK 并非所有 API 都同时支持 Node.js 与浏览器,技能文档给出了权威对照:
| Feature | Node.js | Browser |
|---|---|---|
StorageSharedKeyCredential |
✅ | ❌ |
uploadFile() |
✅ | ❌ |
uploadStream() |
✅ | ❌ |
downloadToFile() |
✅ | ❌ |
downloadToBuffer() |
✅ | ❌ |
uploadData() |
✅ | ✅ |
| SAS generation | ✅ | ❌ |
| DefaultAzureCredential | ✅ | ❌ |
| Anonymous/SAS access | ✅ | ✅ |
关键结论:
- 密钥类能力(共享密钥、SAS 生成、DefaultAzureCredential)仅限 Node.js 服务端——浏览器端绝不能持有账户密钥;
- 文件/流/Buffer 类 IO(
uploadFile、uploadStream、downloadToFile、downloadToBuffer)仅限 Node.js——浏览器统一使用uploadData; - 匿名/SAS 访问在两端均可用——浏览器场景的推荐路径是“服务端签发 SAS + 浏览器携带令牌直接访问”。
最佳实践清单
综合技能文档与上文分析,落地时请遵循以下七条准则:
- 优先 DefaultAzureCredential:用 AAD 身份代替连接字符串与账户密钥,兼顾开发与生产;
- 大文件走流式:
uploadStream/downloadToFile面向 >256MB 文件,控制内存并提升并发吞吐; - 设置正确的内容类型:用
setHTTPHeaders维护准确 MIME、Cache-Control 与 Content-Disposition; - 客户端访问用短时效 SAS:浏览器上传/下载一律通过服务端签发的受限令牌,绝不暴露密钥;
- 优雅处理错误:依据
RestError.statusCode(404/409/403)做分支处理,未识别错误继续抛出; - 善用
*IfNotExists方法:createIfNotExists/deleteIfExists让容器与 Blob 操作幂等化,便于任务重跑; - 长驻进程主动关闭客户端:虽非强制,但在常驻服务中显式清理客户端资源是良好实践。
使用边界与注意事项
技能文档在“When to Use”与“Limitations”中明确了边界:
- 本技能仅适用于与 Azure Blob Storage 对象操作明确匹配的任务(上传、下载、列举、管理 Blob 与容器),不应泛化到其他云存储或非对象存储场景;
- 技能输出不能替代环境级验证、测试与专家评审——尤其是删除、复制、SAS 签发等破坏性或授权类操作,必须在真实环境先行小范围验证;
- 当任务缺少必要输入(账户名、密钥/令牌、权限边界、成功标准)时,应停下来向用户澄清,而非盲目执行。
结合 data/catalog.json 中 risk: critical 的标记可以理解其背后的设计:该技能会直接变更云基础设施状态,因此 AAS 要求 Agent 在调用时保持保守——先确认权限边界,再执行操作,最后验证结果。
结语
azure-storage-blob-ts 技能以一份结构化的操作手册,完整覆盖了 @azure/storage-blob 12.x 从认证、容器管理到 Blob 全生命周期操作的关键路径,并明确了 Node.js 与浏览器双平台的能力边界。配合 AAS 仓库中的技能元数据与社区来源记录,你可以将它作为 Agent 任务路由的触发源,也可以直接将其中的代码范式移植到自己的 TypeScript 工程中——从 DefaultAzureCredential 起步,以 SAS 令牌守住客户端边界,用 RestError 分支建立可观测的错误处理,即可构建一套安全、稳健的 Azure Blob 存储集成。