minio.New初始化后必须立即探活，因它仅解析参数而不发网络请求；endpoint不能带协议前缀，HTTPS需设Secure=true、HTTP设false，错配导致EOF；BucketExists对不存在桶返回false,nil，权限/超时/签名错误均返回err!=nil。
minio.New 初始化后必须立刻探活，否则连接失败不报错
很多人以为 minio.New 返回非 nil 的 client 就代表连上了，其实它只做参数解析，不发任何网络请求。endpoint 写错、TLS 配置反了、AccessKey 权限不足、服务端禁用 v2 签名……全都不会在初始化时暴露。
必须紧接着调用一次实际请求来“探活”，推荐用 client.BucketExists（哪怕传个不存在的桶名）或 client.ListBuckets：
-
endpoint不能带http://或https://前缀，例如填"localhost:9000"，不是"http://localhost:9000" - HTTPS 地址必须设
Secure: true，HTTP 则必须为false；错配会导致EOF或空响应 -
BucketExists对不存在桶返回false, nil，但权限错误、超时、签名不匹配等都会返回err != nil
Gin 路由中上传文件时 PutObject 卡住或报 context deadline exceeded
这不是 SDK bug，而是 HTTP 连接池 + 服务端 Keep-Alive 配置不匹配导致的静默 hang，尤其在短生命周期服务（如 K8s Job、Lambda）里高频复用 client 时极易复现。
关键点不在文件大小，而在上下文和 reader 的使用方式：
立即学习“go语言免费学习笔记（深入）”；
- 务必传入带 timeout 的
context.Context：例如ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Minute) - 避免直接传
[]byte或os.ReadFile结果——大文件会全量进内存，可能 OOM；改用os.Open后传*os.File，SDK 内部会按需流式读取 - 若用
bufio.NewReader包装 reader，注意它不支持重读；上传失败重试前需确保能Seek(0, 0) -
contentType参数不能是空字符串，建议设为"application/octet-stream"或根据扩展名推断（如mime.TypeByExtension(filepath.Ext(name))）
Gin 中 GetObject 下载返回空数据或 EOF 的常见误操作
GetObject 返回的是 *minio.Object，本质是流式 io.ReadCloser。不检查 err 就直接读，90% 的“读不到”问题都源于此。
典型错误包括：
- 调用
client.GetObject后忽略返回的err，直接对obj调用io.Copy或io.ReadAll - 没在 defer 中调用
obj.Close()，导致 fd 泄露，压测时容易崩 - 用
obj.Stat().Size预分配 buffer，但在某些 proxy 场景下该值不准，反而引发截断 - 下载路径含中文或特殊字符时，未确认对象名是否 UTF-8 编码，List 时不会自动 decode
ListObjectsV2 在 Gin 接口里返回空但明明有文件
MinIO 的 ListObjectsV2 默认只列 root 层级，且 prefix 匹配是「前缀严格匹配」，不是模糊搜索。
要让它真正列出内容，必须显式控制两个参数：
- 递归列出所有文件？传
minio.ListObjectsOptions{Recursive: true} -
prefix如果带/结尾（比如"logs/"），它只匹配目录；不带结尾（"logs"）才匹配logs-2024.txt这类文件名 - MinIO 默认不支持通配符，
*或?在prefix里无效 - 如果用了
delimiter（如"/"），它会模拟目录结构，但需手动处理分页和子目录遍历
复杂点在于：Gin 的每个请求生命周期短，但 MinIO client 应全局复用；临时凭证刷新、连接池复用、reader 生命周期管理这些细节，稍一松懈就变成线上静默失败。
