推荐使用 azure.storage.blobs v12+，弃用旧版；初始化 blobserviceclient 时：连接字符串仅限本地调试，共享密钥适用于 ci/cd，azure ad（defaultazurecredential）为生产首选；容器名须全小写、3–63 字符、字母或数字开头结尾；上传大文件必须流式处理。
用 Azure.Storage.Blobs（v12+）才是唯一推荐路径，旧版 Microsoft.Azure.Storage.Blob 已彻底弃用，连 NuGet 包都标记为“deprecated”。
初始化 BlobServiceClient 时该选连接字符串、共享密钥还是 Azure AD？
三者权限模型和适用阶段完全不同，不能混用：
- 连接字符串：仅限本地开发调试；含
AccountKey，硬编码进代码或提交到 Git 是高危操作 - 共享密钥（
StorageSharedKeyCredential）：适合 CI/CD 或容器化部署；账户名 + 密钥分离，可注入环境变量，比连接字符串更可控 - Azure AD（
DefaultAzureCredential）：生产环境首选；依赖Azure.Identity包，自动尝试多种凭据链（托管身份、Azure CLI 登录、VS Code 插件等），无需任何密钥硬编码
示例（Azure AD 方式）：
var serviceClient = new BlobServiceClient(
new Uri("https://myaccount.blob.core.windows.net"),
new DefaultAzureCredential());
注意：国内 Azure China 需把域名换成 https://myaccount.blob.core.chinacloudapi.cn，否则 DNS 解析失败。
上传文件前必须确保容器存在且命名合规
常见 ResourceNotFound 错误 80% 出在这里，不是代码写错，是容器根本没建或名字不合法：
- 容器名必须全小写（如
"logs"合法，"Logs"或"MYCONTAINER"会失败） - 不能含下划线、大写字母、特殊符号；长度 3–63 字符；必须以字母或数字开头和结尾
- 调用
containerClient.CreateIfNotExistsAsync()是安全做法，但别漏掉await—— 忘加会导致后续上传直接报 404
正确写法：
var containerClient = serviceClient.GetBlobContainerClient("mycontainer");
await containerClient.CreateIfNotExistsAsync(PublicAccessType.None);
如果需要匿名读（比如放静态资源），把 PublicAccessType.None 换成 PublicAccessType.Blob。
上传大文件必须用流式，别读全内存
用 File.ReadAllBytes() 加载几百 MB 文件，轻则 GC 压力大，重则 OutOfMemoryException：
- 流式上传：
using var stream = File.OpenRead("large.zip"); await blobClient.UploadAsync(stream); - 若需设置
ContentType或ContentMD5，传BlobHttpHeaders和BlobRequestConditions - 默认不校验 MD5；如需开启，构造
BlobHttpHeaders时设ContentHash并传入UploadOptions
小文件（BinaryData 简洁，但别无脑套用：
await blobClient.UploadAsync("file.txt",
new BinaryData(File.ReadAllBytes("file.txt")),
new BlobHttpHeaders { ContentType = "text/plain" });
下载时别忽略 Progress 和流式处理
下载回调的 Progress<long></long> 参数是已读字节数，不是百分比 —— 得自己算：
- 先
await blobClient.GetPropertiesAsync()拿到ContentLength，再在Progress回调里做除法 - 大文件下载必须用
DownloadToAsync(Stream)，别用DownloadAsync().Value.Content全加载进内存 - 网络中断时，
DownloadToAsync默认不续传；如需断点续传，得自己管理 offset +Range请求头
最容易被忽略的是容器名大小写规则——它不是建议，是强制。哪怕你本地测试用 "MyContainer" 成功了，上线后换到另一台机器或另一套环境，大概率就 404。这不是 SDK Bug，是 Azure 存储服务底层对 DNS 和 URL 路由的硬性要求。
