使用 JavaScript 或 TypeScript 上传一个 Blob

本文介绍如何使用适用于 JavaScript 的 Azure 存储客户端库上传 blob。可以通过文件路径、流、缓冲区或文本字符串将数据上传到块 Blob。还可以上传带有索引标记的 Blob。

先决条件

本文中的示例假设你已经设置了一个项目来使用适用于 JavaScript 的 Azure Blob 存储客户端库。若要了解如何设置项目（包括安装包、导入模块，以及创建授权客户端对象来使用数据资源），请参阅开始使用 Azure Blob 存储和 JavaScript。
授权机制必须具有执行上传操作的权限。若要了解详细信息，请参阅以下 REST API 操作的授权指南：
- 放置 Blob
- 放置块

将数据上传到块 Blob

可以使用以下任一方法将数据上传到块 Blob：

upload（非并行上传方法）
uploadData
uploadFile（仅适用于 Node.js 运行时）
uploadStream（仅适用于 Node.js 运行时）

可以使用 BlockBlobClient 对象调用其中每种方法。

注释

Azure 存储客户端库不支持对同一 Blob 的并发写入。如果应用需要向同一 Blob 写入多个进程，则应实施并发控制策略以提供可预测的体验。若要详细了解并发策略，请参阅管理 Blob 存储中的并发性。

通过本地文件路径上传块 Blob

以下示例通过本地文件路径上传块 Blob：

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadBlobFromLocalPath(containerClient, blobName, localFilePath){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

async function uploadBlobFromLocalPath(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

通过流上传块 Blob

以下示例通过创建并上传可读流来上传块 Blob：

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// readableStream: Readable stream, for example, a stream returned from fs.createReadStream()
async function uploadBlobFromReadStream(containerClient, blobName, readableStream) {
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload data to block blob using a readable stream
  await blockBlobClient.uploadStream(readableStream);
}

async function uploadBlobFromReadStream(
  containerClient: ContainerClient,
  blobName: string,
  readStream: fs.ReadStream
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadStream(readStream);
}

通过缓冲区上传块 Blob

以下示例通过 Node.js 缓冲区上传块 Blob：

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// buffer: blob contents as a buffer, for example, from fs.readFile()
async function uploadBlobFromBuffer(containerClient, blobName, buffer) {

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

async function uploadBlobFromBuffer(
  containerClient: ContainerClient, blobName: string, buffer: Buffer
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

通过字符串上传块 Blob

以下示例通过字符串上传块 Blob：

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// fileContentsAsString: blob content
async function uploadBlobFromString(containerClient, blobName, fileContentsAsString){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length);
}

async function uploadBlobFromString(
  containerClient: ContainerClient,
  blobName: string,
  fileContents: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContents, fileContents.length);
}

使用配置选项上传块 Blob

上传 blob 时，可以定义客户端库配置选项。可以优化这些选项以提高性能、增强可靠性和优化成本。本部分中的代码示例展示了如何使用e BlockBlobParallelUploadOptions 接口设置配置选项，以及如何将这些选项作为参数传递给上传方法调用。

在上传时指定数据传输选项

可以配置 BlockBlobParallelUploadOptions 中的属性以提高数据传输操作的性能。下表列出了可以配置的属性及其说明：

财产	说明
`blockSize`	作为上传操作的一部分，每个请求传输的最大块大小。
`concurrency`	在任何给定时间，作为单个并行传输的一部分发出的最大并行请求数量。
`maxSingleShotSize`	如果数据大小小于或等于此值，则会以单个输入上传，不会拆分成多个区块。如果数据是一次性上传的，则会忽略该块大小。默认值为 256 MiB。

以下代码示例演示如何设置 BlockBlobParallelUploadOptions 的值并将选项作为上传方法调用的一部分包含在内。此示例中提供的值不作为建议。若要正确优化这些值，需要考虑应用的特定需求。

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithTransferOptions(containerClient, blobName, localFilePath) {
  
  // Specify data transfer options
  const uploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  } 

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with transfer options
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

async function uploadWithTransferOptions(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify data transfer options
  const uploadOptions: BlockBlobParallelUploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

若要详细了解如何优化数据传输选项，请参阅优化 JavaScript 的上传和下载性能。

指定上传时的数据传输校验

使用 CRC64 的传输验证为Azure Blob 存储提供客户端级数据完整性，使你能够验证应用程序发送的数据是否与从Azure中存储和读取的数据相同。启用后，Blob SDK 会在上传和下载操作期间计算并验证 CRC64 校验和，而服务会独立计算并验证其接收和返回的数据的 CRC64 校验和。对每个请求以及整个数据流进行验证，确保即使数据以分区方式传输（如块上传或范围读取），整个 Blob 也都能得到验证。有关更多详细信息，请参阅结构化正文格式。

可以使用 BlobClientConfig 在客户端级别定义传输验证选项，该配置将验证选项应用于从 BlobClient 实例调用的所有方法。或者，可以通过 BlobUploadOptions 等选项替代操作级别的传输验证选项。

JavaScript
TypeScript

const blobServiceClient = new BlobServiceClient(
   `https://${account}.blob.core.chinacloudapi.cn`,
   new DefaultAzureCredential(),
   {
     uploadContentChecksumAlgorithm: "StorageCrc64",
     downloadContentChecksumAlgorithm: "StorageCrc64",
   }
);

 const blobServiceClient: BlobServiceClient = new BlobServiceClient(
   `https://${account}.blob.core.chinacloudapi.cn`,
   new DefaultAzureCredential(),
   {
     uploadContentChecksumAlgorithm: "StorageCrc64",
     downloadContentChecksumAlgorithm: "StorageCrc64",
   },
);

上传带有索引标记的块 Blob

Blob 索引标记使用键值标记属性对存储帐户中的数据进行分类。这些标记会自动索引，并作为可搜索的多维索引公开，便于你轻松查找数据。

以下示例上传一个使用 BlockBlobParallelUploadOptions 设置了索引标记的块 Blob：

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithIndexTags(containerClient, blobName, localFilePath) {
  
  // Specify index tags for blob
  const uploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

async function uploadBlobWithIndexTags(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify index tags for blob
  const uploadOptions: BlockBlobParallelUploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

上传时设置 Blob 的访问层

可以使用 BlockBlobParallelUploadOptions 接口在上传时设置 Blob 的访问层。以下代码示例演示如何在上传 blob 时设置访问层：

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithAccessTier(containerClient, blobName, localFilePath) {
  
  // Specify access tier
  const uploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool',
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob to cool tier
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

async function uploadBlobWithAccessTier(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {

  // Upload blob to 'Cool' access tier
  const uploadOptions: BlockBlobParallelUploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool'
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

仅允许针对块 Blob 设置访问层。可以将块 blob 的访问层设置为 Hot、Cool、Cold 或 Archive。若要将访问层设置为 Cold，必须至少使用客户端库版本 12.13.0。

若要详细了解访问层，请参阅访问层概述。

资源

若要详细了解如何使用适用于 JavaScript 的 Azure Blob 存储客户端库来上传 Blob，请参阅以下资源。

REST API 操作

Azure SDK for JavaScript 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 JavaScript 范例与 REST API 操作进行交互。用于上传 blob 的客户端库方法使用以下 REST API 操作：

放置 Blob (REST API)
放置块 (REST API)

代码示例

查看本文中的代码示例 (GitHub)：

通过本地文件路径上传（适用于 JavaScript 或 TypeScript）
通过缓冲区上传（适用于 JavaScript 或 TypeScript）
通过流上传（适用于 JavaScript 或 TypeScript）
通过字符串上传（适用于 JavaScript 或 TypeScript）
使用 JavaScript 或 TypeScript 的传输选项进行上传
使用 JavaScript 或 TypeScript 的索引标记进行上传
使用 JavaScript 或 TypeScript 的访问层进行上传

客户端库资源

另请参阅

本文是适用于 JavaScript/TypeScript 的 Blob 存储开发人员指南的一部分。要了解详细信息，请参阅构建 JavaScript/TypeScript 应用中的完整开发人员指南文章列表。

Last updated on 2026-07-02