MinIO Go客户端初始化失败主因是endpoint协议与Secure参数不匹配：本地开发须用"http://localhost:9000"且Secure设为false，生产环境用"https://域名"且Secure为true；FPutObject必须显式传入PutObjectOptions{}并手动设置ContentType。
MinIO Go 客户端不是“换个方式存文件”，而是用 S3 协议接管整个非结构化数据流——上传、下载、权限、生命周期都得按对象存储的逻辑重新建模，否则本地文件系统那一套会直接失效。
minio.New 初始化失败：Secure 和 endpoint 的坑比想象中多
常见错误是 minio.New("localhost:9000", ...) 直接 panic，报错类似 unable to parse endpoint 或 invalid URL scheme。根本原因不是地址写错，而是 MinIO Go v7 强制要求 endpoint 必须带协议且不能带路径——"http://localhost:9000" 才合法，"localhost:9000" 或 "http://localhost:9000/minio" 都会挂。
Secure 参数必须和实际服务一致：Secure: true 时，endpoint 必须是 https://...；Secure: false 时，endpoint 必须是 http://...。本地开发常用 HTTP，但很多人漏设 Secure: false，导致客户端强行走 TLS 握手失败。
- MinIO Server 默认启 HTTP（9000 端口）和 HTTPS（9001 端口），但仅当配置了证书才真正启用 HTTPS
- 若用 Docker 启动未挂载证书，
Secure: true一定失败 - 推荐开发期统一用
Secure: false+"http://localhost:9000"
FPutObject 上传空文件或超时：PutObjectOptions 缺失关键配置
调用 FPutObject 上传本地文件却卡住、返回 context deadline exceeded，或上传后文件大小为 0，通常是因为没传 minio.PutObjectOptions{} ——哪怕空 struct 也必须显式传入。v7 版本已移除默认选项，不传就 panic。
立即学习“go语言免费学习笔记（深入）”；
更隐蔽的问题是 Content-Type 自动推断失效：FPutObject 不读文件扩展名，也不查 magic bytes，它完全依赖你手动设置 ContentType 字段。图片传成 text/plain，浏览器就直接下下载而不是渲染。
- 上传前建议用
mime.TypeByExtension(filepath.Ext(path))获取类型 - 小文件（PutObject，避免临时文件 I/O
- 大文件务必设
ctx超时，例如context.WithTimeout(context.Background(), 5*time.Minute)
GetObject 返回 *minio.Object 不是 []byte：别直接 json.Marshal
调用 GetObject 得到的是一个 *minio.Object，它实现了 io.ReadCloser，但不是字节切片。有人直接 json.Marshal(obj) 或 string(obj)，结果得到空字符串或 panic。
正确做法是先读取全部内容再处理：data, err := io.ReadAll(obj)。但要注意，obj.Close() 必须调用，否则连接不释放，跑几次就耗尽客户端连接池。
- 如果只是想保存到磁盘，用
FGetObject更省事，不用管 Reader/Close - 流式处理（比如边读边解压）必须用
GetObject+io.Copy，但记得 defer obj.Close() - HTTP header 如
x-amz-meta-*存在obj.Stat().Metadata里，不是 response body
BucketExists 判断不准：不是所有 403 都代表桶不存在
BucketExists 返回 false, nil 时，大多数人认为桶一定不存在。但其实当 client 权限不足（比如只读策略没覆盖该桶），也会返回 false, nil ——这是 S3 协议设计的“安全沉默”，避免信息泄露。
真正可靠的判断方式是捕获 error 并检查类型：minio.ToErrorResponse(err).Code == "NoSuchBucket"。其他 error（如 AccessDenied）说明桶存在但无权访问。
- 不要用
BucketExists做权限校验，它不是权限 API - 生产环境应预置桶，而非运行时动态创建，避免并发创建冲突
- 若必须动态创建，
MakeBucket失败时需检查ErrBucketAlreadyOwnedByYou而非忽略
MinIO 的 Go SDK 表面简单，但每个函数背后都绑着 S3 协议语义、HTTP 生命周期和连接复用机制。最常被忽略的是：它不维护任何本地状态，所有操作都是无状态 HTTP 请求——这意味着重试逻辑、连接池大小、DNS 缓存、TLS 会话复用，全得你自己盯紧。
