MinIO SDK for .NET 官方唯一维护的 NuGet 包是 Minio，需执行 dotnet add package Minio；endpoint 必须带协议且不带路径，如 "https://minio.example.com"；客户端应单例复用，GetObjectAsync 返回流须用 using 确保释放。
MinIO SDK for .NET 要用哪个包？别装错
官方只维护 Minio 这一个 NuGet 包，不是 Minio.Net、MinioClient 或任何带后缀的变体。装错包会导致命名空间找不到、MinioClient 类型不存在等编译错误。
- 正确命令：
dotnet add package Minio（最新稳定版已支持 .NET 6+，无需降级） - 旧项目若用 .NET Framework 4.6.1+，也兼容，但别选
Minio.NetCore——那是过时的社区 fork，无维护 - SDK 不依赖
Newtonsoft.Json，用的是System.Text.Json，若项目强制用 Newtonsoft，注意反序列化行为差异（比如空字符串 vs null 处理）
初始化 MinioClient 时 endpoint 和 credentials 怎么填？
endpoint 必须带协议且**不能带路径**，比如 "https://minio.example.com" 合法，"https://minio.example.com/minio" 或 "http://localhost:9000/"（末尾斜杠）会直接报 Invalid URI: The hostname could not be parsed.
- Access key 和 Secret key 来自 MinIO server 启动时设置的
MINIO_ROOT_USER/MINIO_ROOT_PASSWORD，不是浏览器登录后的临时 token - 本地调试用 Docker 启动时，常见错误是把
localhost写进 endpoint——.NET 容器内访问宿主需换为host.docker.internal（Windows/macOS）或宿主真实 IP（Linux） - SSL 验证默认开启，自签名证书会抛
HttpRequestException: The SSL connection could not be established.，临时绕过要传httpClientHandler.ServerCertificateCustomValidationCallback = (a, b, c, d) => true;，但上线前必须配可信证书
上传文件用 PutObjectAsync 还是 StreamUploadAsync？
PutObjectAsync 是最常用方式，适合已知大小、可读流明确的场景；StreamUploadAsync 是为超大文件（GB 级）分块上传设计的，但需要自己处理分片逻辑和断点续传，一般没必要用。
- 上传小文件（FileStream 或
MemoryStream，指定contentType（如"image/png"），否则 MinIO 默认存为application/octet-stream，前端下载可能无法正确渲染 - 上传大文件（>100MB）：建议先用
StatObjectAsync检查 bucket 是否存在，再调PutObjectAsync——它内部已做分块，不需要手动切片 - 别在循环里反复 new
MinioClient，它本身是线程安全的，应作为单例复用；否则会快速耗尽 socket 连接，出现SocketException: Too many open files
下载文件时 GetObjectAsync 返回的 Stream 怎么安全读取？
GetObjectAsync 返回的是一个未缓冲的网络流，不支持 Seek，也不能多次读取。直接调 stream.CopyTo(response.Body) 是常见做法，但容易忽略异常时流未释放的问题。
- 务必用
using var stream = await client.GetObjectAsync(...)，否则连接不会及时归还连接池，高并发下很快触发TimeoutException: Unable to read data from the transport connection - 如果要校验文件完整性，得在读取前先调
StatObjectAsync拿到ETag（即 MD5 值），再和本地计算的 MD5 对比——MinIO 不提供服务端校验接口 - 前端下载大文件时，别一次性
ToArray()加载进内存，容易 OOM；用Response.Body分段写入，配合Content-Disposition: attachment; filename="xxx"头让浏览器触发保存
MinIO 的对象操作看似简单，但 endpoint 格式、证书验证、流生命周期这三处最容易卡住人。尤其是本地开发时混用 localhost 和容器网络，问题现象五花八门，其实根源就那两三个配置点。
