用途
@azure/storage-blob 是用于 Azure Blob Storage 操作的 JavaScript/TypeScript SDK，可用于上传、下载、列举、复制、删除及管理 Blob 和容器。该技能文档面向需要以 Node.js 或浏览器访问 Azure Blob 存储的开发者。
安装与环境
安装命令：npm install @azure/storage-blob @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（推荐）、Connection String、StorageSharedKeyCredential（仅 Node.js）、SAS Token。每种方式均提供对应的初始化代码示例，例如推荐方式使用 new BlobServiceClient(\https://${accountName}.blob.core.windows.net`, new DefaultAzureCredential())`。
客户端层级
BlobServiceClient（账户级）→ ContainerClient（容器级）→ BlobClient（Blob 级），BlobClient 下又分为 BlockBlobClient（块 Blob，最常见）、AppendBlobClient（仅追加）、PageBlobClient（页 Blob，用于 VHD）。
主要能力
容器操作
创建容器（create / createIfNotExists）、列举容器（listContainers，支持 prefix 过滤）、删除容器（delete / deleteIfExists）。
Blob 操作
- 上传：简单上传（字符串或 Buffer）、从文件上传（uploadFile，仅 Node.js）、从流上传（uploadStream，含缓冲大小、并发数与进度回调）、浏览器上传（uploadData，支持 File、Blob/ArrayBuffer）。
- 下载：download 并读取为字符串、下载到文件（downloadToFile，仅 Node.js）、下载到 Buffer（downloadToBuffer，仅 Node.js）。
- 列举：listBlobsFlat（全部或按 prefix）、listBlobsByHierarchy（虚拟目录）。
- 删除：delete、deleteIfExists、删除时包含快照（deleteSnapshots: "include"）。
- 复制：beginCopyFromURL 并 pollUntilDone 等待完成。
- 属性与元数据：getProperties（contentType、contentLength、lastModified、etag 等）、setMetadata、setHTTPHeaders。
SAS 令牌生成（仅 Node.js）
支持生成 Blob SAS、Container SAS、Account SAS，示例包含权限解析（如 BlobSASPermissions.parse("r")、ContainerSASPermissions.parse("racwdl")、AccountSASPermissions.parse("rwdlacupi")）与过期时间设置。
Blob 类型
- 块 Blob（默认）：适用于文本和二进制文件的常见类型。
- 追加 Blob：针对追加操作优化（日志、审计跟踪），示例包含 create 与 appendBlock。
- 页 Blob：固定大小、随机读写（VHD），需 512 字节对齐，示例包含 create 与 uploadPages。
错误处理
使用 RestError，根据 statusCode 区分 404（容器不存在）、409（已存在）、403（拒绝访问）等情况。
TypeScript 类型
文档列出可导入的客户端、认证、SAS、选项与响应、错误等类型名称。
适用场景
需要以 TypeScript/JavaScript 编程方式操作 Azure Blob 存储的场合，包括上传与下载文件、列出/管理容器与 Blob、生成 SAS 令牌供客户端访问、按需选择块/追加/页 Blob 类型，以及在 Node.js 或浏览器环境中使用不同能力。
最佳实践
- 优先使用 DefaultAzureCredential（AAD），少用连接字符串/密钥。
- 大文件（>256MB）使用流式上传/下载。
- 通过 setHTTPHeaders 设置正确的 MIME 内容类型。
- 浏览器上传使用短时 SAS 令牌。
- 使用 RestError.statusCode 做针对性错误处理。
- 使用 *IfNotExists 方法实现幂等创建。
- 长时运行应用建议关闭客户端（非必需）。
平台差异
StorageSharedKeyCredential、uploadFile()、uploadStream()、downloadToFile()、downloadToBuffer()、SAS 生成、DefaultAzureCredential 仅支持 Node.js；uploadData() 与匿名/SAS 访问在 Node.js 和浏览器均支持。
限制
仅当任务明确匹配上述范围时使用。不得将输出视为环境特定验证、测试或专家评审的替代。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。