MinIO C# SDK在.NET 6+需禁用HttpClient自动解压，初始化时须传入AutomaticDecompression=None的HttpClient；上传Stream需重置位置，contentType不可为空；ListObjectsAsync的prefix须带尾部/且recursive=true才正确匹配子路径；Presigned URL时间以服务端UTC为准。
MinIO 的 C# SDK（Minio NuGet 包）本身不支持 .NET 6+ 默认启用的 HttpClientHandler.AutomaticDecompression，直接调用会触发 System.Net.Http.HttpRequestException: Response status code does not indicate success: 500 (Internal Server Error) 或静默解压失败 —— 这是新手最常卡住的第一步。
安装 MinIO 官方 SDK 并禁用自动解压
官方 Minio 包（v4.x）底层复用了旧版 HttpClient 初始化逻辑，若运行在 .NET 6+ 上，它会继承全局 HttpClientHandler 的 AutomaticDecompression = GZip | Deflate 设置，而 MinIO Server（尤其早期版本）不兼容带 Accept-Encoding: gzip 的请求，直接返回 500。
- 执行
dotnet add package Minio（确认版本 ≥ 4.0.5，低于此版本需手动 patch） - 初始化客户端时必须显式传入自定义
HttpClient，且其Handler的AutomaticDecompression设为None - 不要用默认构造函数
new MinioClient(...)，它会偷偷创建带自动解压的HttpClient
var handler = new HttpClientHandler
{
AutomaticDecompression = DecompressionMethods.None
};
var httpClient = new HttpClient(handler);
var minio = new MinioClient(
"https://play.min.io",
"Q3AM3UQ867SPQQA43P2F",
"zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
httpClient: httpClient
);
上传文件时注意 Stream 生命周期和 Content-Type
调用 PutObjectAsync 传入的 Stream 必须保持打开状态直到上传完成，且 SDK 不会帮你重置位置（Seek(0, SeekOrigin.Begin)）。如果从 FileStream 或内存 MemoryStream 读取后未重置，会上传空内容或抛 ObjectDisposedException。
- 对
MemoryStream：上传前务必调用stream.Position = 0 - 对
FileStream：确保以FileAccess.Read打开，且未被其他线程/代码Dispose -
contentType参数不能为null；若不确定，用"application/octet-stream"最安全，不要依赖 SDK 自动推断 - 大文件（>100MB）建议分块上传（
ComposeObjectAsync或直传 presigned URL），避免内存暴涨和超时
列出对象时 prefix 和 recursive 行为与 AWS S3 不完全一致
MinIO 的 ListObjectsAsync 中 recursive: true 并非“深度遍历子目录”，而是等价于 delimiter = ""；若设 recursive: false（默认），则只返回当前层级、不带 / 后缀的对象 —— 它不会模拟“目录结构”，也不会过滤出“伪目录”。
- 想获取某个路径下的所有对象（如
logs/2024/），必须显式设置prefix = "logs/2024/"，且recursive = true - MinIO 不返回
CommonPrefixes（即“目录”），所以无法用 S3 兼容方式做分层浏览；需要自己按/切割object.Key并去重 - 若
prefix末尾漏掉/（比如写成"logs/2024"），会匹配到logs/202401.txt这类名字含前缀但非子路径的对象
Presigned URL 过期时间受服务端 UTC 时间影响
MinIO Server 生成 presigned URL 时使用的是自身系统时间（UTC），而非客户端时间。若服务器时钟偏差 > 15 分钟，客户端签名会因 X-Amz-Date 被拒绝，报错 InvalidRequest: The difference between the request time and the server's time is too large.
- 检查 MinIO 服务端时间是否同步：在运行 MinIO 的机器上执行
date -u - 避免在容器中运行 MinIO 时未挂载宿主机时区或未启用
systemd-timesyncd/chrony - 生成 URL 时传入的
expiresIn是从服务端当前时间起算，不是客户端时间，所以客户端无需校准本地时钟
MinIO 的 C# SDK 看似简单，但每个核心操作背后都藏着服务端行为、HTTP 协议细节和 .NET 运行时演进的耦合点。最容易被忽略的是：它不是“开箱即用”的封装，而是对 S3 协议的轻量适配 —— 你得同时懂 MinIO Server 的配置边界、S3 API 的语义、以及 .NET HttpClient 的隐式行为。
