Azurite非默认端口下BlobServiceClient调用异常排查

核心原因 #

当使用非默认端口（10020）时，Azure Blobs SDK默认采用子域名风格的账户解析逻辑，但你构造BlobServiceClient时使用的是路径风格的Uri（即账户名放在路径中：http://localhost:10020/account），两者不匹配导致SDK生成请求URL时路径拼接异常，最终缺失/container部分，触发Azurite返回400错误。

而默认端口10000时SDK会自动兼容路径风格的Uri，所以一切正常。

两种可行解决方案 #

方案1：改用子域名风格构造Uri #

将账户名作为子域名添加到Uri中，SDK会正确识别账户并生成正确的请求路径：

services.AddAzureClients(builder =>
{
    builder.AddBlobServiceClient(
        new Uri("http://account.localhost:10020/"),
        new StorageSharedKeyCredential("account", "QUJDRA=="));
});

注：localhost的子域名默认会解析到本地，无需额外配置hosts。

方案2：强制SDK使用路径风格路由 #

通过BlobClientOptions开启UsePathStyleRouting，强制SDK始终按路径风格解析账户名，不受端口影响：

services.AddAzureClients(builder =>
{
    builder.AddBlobServiceClient(
        new Uri("http://localhost:10020/account"),
        new StorageSharedKeyCredential("account", "QUJDRA=="))
    .WithOptions(options =>
    {
        options.UsePathStyleRouting = true;
    });
});

验证效果 #

采用任一方案后，Azurite日志中会显示完整的请求URL（如http://localhost:10020/account/container/blob），文件上传功能恢复正常。

内容的提问来源于stack exchange，提问作者Daniel García Rubio