minio初始化报错invalid endpoint的主因是endpoint格式错误：必须带http://或https://协议头，且严禁包含路径（如/minio）或尾部斜杠；docker内访问宿主需用host.docker.internal（win/macos）或宿主真实ip（linux）。
MinioClient 初始化必须避开的 endpoint 格式陷阱
直接报错 Invalid URI: The hostname could not be parsed. 的绝大多数情况，都是因为 endpoint 字符串写错了。它必须带协议（http:// 或 https://），且**不能带任何路径或尾部斜杠**。
-
"https://minio.example.com"✅ 合法 -
"https://minio.example.com/minio"❌ 报错：路径部分会被解析成主机名 -
"http://localhost:9000/"❌ 末尾斜杠触发解析失败 - Docker 内访问宿主时，别用
localhost—— Windows/macOS 改用http://host.docker.internal:9000，Linux 用宿主真实 IP
AccessKey 和 SecretKey 必须是启动 MinIO 时设置的 MINIO_ROOT_USER/MINIO_ROOT_PASSWORD，不是浏览器登录后生成的临时 token。
上传文件时 contentType 不设就等于埋雷
不显式指定 contentType，MinIO 默认存为 application/octet-stream。这会导致前端通过 URL 直接访问图片、PDF 等资源时无法正确渲染或触发下载，而不是按预期展示。
- 上传 PNG：
contentType: "image/png" - 上传 JSON：
contentType: "application/json" - 上传 HTML：
contentType: "text/html; charset=utf-8" - 若传
null或空字符串，SDK 会 fallback 到默认值，等同于没设
示例调用：await client.PutObjectAsync("mybucket", "logo.png", stream, stream.Length, "image/png");
PutObjectAsync 是主力，别被 StreamUploadAsync 带偏
PutObjectAsync 覆盖 95% 的上传场景；StreamUploadAsync 是为 GB 级大文件分块上传设计的，但需要你手动管理分片、ETag 校验、断点续传逻辑，官方示例里都极少用到。
- 已知大小、流可 seek（如
FileStream）→ 无脑用PutObjectAsync - 流不可 seek（如网络请求 Body 流）且体积不大（PutObjectAsync，传
-1作为 size，SDK 内部会转成 chunked 上传 - 真要上传超大文件且需断点续传 → 自建分片逻辑 +
ComposeObjectAsync拼接，而非依赖StreamUploadAsync
注意：PutObjectAsync 返回的是 Task，务必 await，否则可能丢异常或上传中断不报错。
客户端单例复用 + 流释放是性能与稳定双保险
每次上传都 new 一个 MinioClient，不仅浪费连接池资源，还会在高并发下触发 socket 耗尽或 TLS 握手延迟。同时，GetObjectAsync 返回的流若不用 using 包裹，会持续占用 HTTP 连接，最终卡死后续请求。
- 全局只初始化一次
MinioClient实例，注入 DI 容器或用static readonly持有 - 上传用的
Stream（如FileStream）建议也用using，避免句柄泄漏 - 下载时务必这样写：
using var stream = await client.GetObjectAsync(...);，别只 await 不 using - 自签名证书调试时临时绕过 SSL 验证，必须用
httpClientHandler.ServerCertificateCustomValidationCallback = (a,b,c,d) => true;，上线前删掉
容易被忽略的一点：SDK 内部用的是 System.Text.Json，如果你项目强制依赖 Newtonsoft.Json 且做了全局配置（如空字符串转 null），反序列化响应体时行为可能不一致——这不是 bug，是底层序列化器切换带来的副作用。
