使用Azure TypeScript SDK上传PDF时遇无效HTTP Header错误求助

问题场景 #

使用Azure TypeScript SDK v12.24.0上传PDF文档至Blob Storage，已确认权限正常（xlsx、csv、png等格式均可正常上传），但上传PDF时触发**"Invalid HTTP Header"**错误。

相关代码 #

const blockBlobClient: BlockBlobClient = this.azureClient.getBlockBlobClient(store.key);
await blockBlobClient.uploadStream(readStream, undefined, undefined, {
  blobHTTPHeaders: {
    blobContentType: 'application/pdf',
  },
  onProgress: (progress) => {
    this.logger.debug(progress);
  }
}).catch((error) => {
  this.logger.error(`Error uploading to Azure Blob Storage: ${error.message}`);
  throw new Error(`Failed to upload file to Azure: ${error.message}`);
});
this.logger.debug(`"${store.key}" uploaded to Azure Blob storage.`);
} else {
  throw new Error("No client found");
}

环境信息 #

• Node: v22.2.0
• Browser: Arc
• SDK: @azure/storage-blob v12.24.0

可能原因及解决方案 #

1. Blob名称包含非法字符 #

Azure Blob存储对Blob名称有严格字符限制，禁止使用控制字符、\ / : * ? " < > |等特殊符号。如果PDF对应的store.key包含这些非法字符，会导致SDK构造HTTP请求头时异常，而其他格式文件名刚好符合规则。

解决方案：
检查并清理store.key，移除所有非法字符，例如将特殊符号替换为下划线或其他合法字符。

2. SDK版本的已知bug #

Azure SDK for JS v12.24.0的uploadStream方法存在与特定Content-Type处理相关的HTTP头构造问题，社区已有相关反馈，application/pdf类型可能触发该bug。

解决方案：

• 降级SDK到v12.23.0，或升级到v12.25.0及以上版本；
• 临时替换上传方法，改用uploadData（将流转换为Buffer后上传），示例代码如下：

// 将readStream转换为Buffer
const buffer = await new Promise<Buffer>((resolve, reject) => {
  const chunks: Uint8Array[] = [];
  readStream.on('data', (chunk) => chunks.push(chunk));
  readStream.on('end', () => resolve(Buffer.concat(chunks)));
  readStream.on('error', reject);
});

const blockBlobClient: BlockBlobClient = this.azureClient.getBlockBlobClient(store.key);
await blockBlobClient.uploadData(buffer, {
  blobHTTPHeaders: {
    blobContentType: 'application/pdf',
  },
  onProgress: (progress) => {
    this.logger.debug(progress);
  }
}).catch((error) => {
  this.logger.error(`Error uploading to Azure Blob Storage: ${error.message}`);
  throw new Error(`Failed to upload file to Azure: ${error.message}`);
});

3. 流处理异常导致头构造错误 #

PDF文件的读取流可能包含异常字节，导致SDK在解析流并构造请求头时出错，而其他格式的流结构不会触发该问题。

解决方案：

• 验证PDF文件本身是否损坏，尝试用其他工具打开确认文件完整性；
• 显式指定请求头，在上传配置中额外添加headers参数强制设置Content-Type：

await blockBlobClient.uploadStream(readStream, undefined, undefined, {
  blobHTTPHeaders: {
    blobContentType: 'application/pdf',
  },
  headers: {
    'Content-Type': 'application/pdf'
  },
  onProgress: (progress) => {
    this.logger.debug(progress);
  }
})

内容的提问来源于stack exchange，提问作者Lawrence Aiello