MinIO客户端初始化需严格匹配协议与端口：endpoint须为"host:port"格式，Secure参数必须显式设为false（HTTP）或true（HTTPS），否则连接失败；上传前须先创建桶并忽略ErrBucketAlreadyOwnedByYou；大文件应流式上传并设context timeout；ListObjectsV2递归需Recursive:true；GetObject后必须defer obj.Close()。
minio.New 传参必须严格匹配协议与端口，否则连接直接失败
MinIO 客户端初始化不是“填个地址就行”，minio.New 的 endpoint 必须是纯主机+端口格式（如 "localhost:9000"），不能带 http:// 或尾部斜杠；secure 参数决定底层是否走 TLS——本地开发没证书时必须显式设为 false，否则默认 true 会强制走 HTTPS，连 HTTP 地址也拒绝。
常见错误现象：connection refused 或 context deadline exceeded，本质是协议/端口不匹配。比如 MinIO 启动用的是 --address :9000（HTTP），但客户端 endpoint 写成 "https://localhost:9000" 或漏掉 Secure: false，必然卡在连接层。
- 确认 MinIO 启动命令：无 TLS 时用
minio server /data --address :9000 - Go 初始化代码必须写成：
minio.New("localhost:9000", &minio.Options{Creds: ..., Secure: false}) - 若用 Docker 启动且挂了证书，endpoint 仍为
"localhost:9000"，但Secure: true
上传前必须显式创建桶，且要正确处理 ErrBucketAlreadyOwnedByYou
MinIO 不像本地文件系统那样“路径不存在就自动 mkdir”，PutObject 绝对不会自动建桶。桶不存在时直接调用 PutObject 会返回 NoSuchBucket 错误，而不是帮你创建。
正确流程是先 BucketExists 检查，再按需 MakeBucket，且必须捕获并忽略 minio.ErrBucketAlreadyOwnedByYou ——这个错误表示桶已存在且归属当前账号，不是异常。
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
-
MakeBucket的 region 参数目前只支持"us-east-1"，填其他值会静默失败 - 桶名必须全小写、3–63 字符、不含下划线或点号、不能是 IP 格式（如
"192.168.1.1"） - 不要用嵌套名，
"my-app/logs"是非法桶名，只能是"my-app"
大文件上传必须用流式 reader + 显式 context timeout，否则 OOM 或超时
直接传 bytes.NewReader(data) 或 os.ReadFile 加载整个文件到内存，对 >100MB 的文件极易触发 GC 压力甚至 OOM。PutObject 默认会把整个 io.Reader 读进内存再分块，这不是 bug，而是设计如此。
正确做法是打开文件后直接传 *os.File，并用 context.WithTimeout 控制整体上传时间：
- 文件打开后立即传入：
file, _ := os.Open("large.zip")→client.PutObject(ctx, "bucket", "key", file, -1, opts) -
-1表示长度未知，SDK 自动按默认 5MB 分块；如需自定义，用minio.PutObjectOptions{PartSize: 10*1024*1024} - 务必检查返回的
minio.UploadInfo.Size是否等于源文件Stat().Size()，防止网络中断导致静默截断
ListObjectsV2 递归列出文件必须设 Recursive: true，prefix 匹配很严格
ListObjectsV2 默认只列 root 层级对象，且 prefix 是前缀精确匹配，不是模糊搜索。比如想列出 "logs/app-202406.log" 和 "logs/error/trace.log"，只传 prefix: "logs" 是不够的。
要真正递归列出所有子路径下的对象，必须显式启用 Recursive: true：
-
prefix: "logs/"（结尾带斜杠）只匹配目录层级，"logs"（不带斜杠）才匹配文件名以logs开头的对象 - MinIO 不支持通配符，
*或?在prefix中无效 - 中文或特殊字符对象名需确保上传时用 UTF-8 编码，List 时不会自动 decode，保持一致性即可
最易被忽略的是 GetObject 返回的 *minio.Object 必须手动 defer obj.Close()，否则 fd 泄露会在压测中迅速崩掉服务；还有 contentType 不能为空字符串，建议设为 "application/octet-stream" 或根据扩展名推断。
