minio客户端需手动初始化并校验错误，桶创建前须用bucketexists检查存在性，putobject需确保reader可重读、contenttype非空且时间同步，客户端应全局复用并注意临时凭证刷新。
MinIO 在 Go 里不是“配好就能用”，而是得手动处理客户端初始化、凭证校验、桶存在性检查和对象上传的错误路径——漏掉任意一环，PutObject 就会静默失败或 panic。
如何正确初始化 MinIO 客户端（避免 nil pointer dereference）
常见错误是直接传空字符串给 minio.New，或忽略返回的 err 就调用方法。MinIO 客户端初始化不校验 endpoint 是否可达，但后续所有操作都会因 client == nil 或未认证而崩溃。
-
endpoint不能带http://或https://前缀（例如填"localhost:9000"，不是"http://localhost:9000"） - 必须显式传入
secure: false（本地开发）或true（HTTPS 生产环境），否则默认为true，连 HTTP 地址都会被拒绝 - 务必检查
minio.New返回的err：网络不通、DNS 失败、TLS 配置错误都会在这里暴露
示例：
client, err := minio.New("localhost:9000", &minio.Options{
Creds: credentials.NewStaticV4("minioadmin", "minioadmin", ""),
Secure: false,
})
if err != nil {
log.Fatal(err) // 不要忽略
}
为什么 MakeBucket 要先检查桶是否存在
MinIO 的 MakeBucket 不是幂等操作：桶已存在时会返回 minio.BucketAlreadyOwnedByYou 错误，而非静默跳过。若没做判断就直接调用，每次运行都可能 panic 或中断流程。
- 正确做法是先调用
BucketExists，再按需创建 -
BucketExists本身也会返回错误（如网络超时、权限不足），不能只看布尔返回值 - MinIO 默认不支持嵌套桶（即路径式桶名），
"my-app/logs"是非法桶名，只能是"my-app"
示例：
exists, err := client.BucketExists(ctx, "my-bucket")
if err != nil {
log.Fatal(err)
}
if !exists {
err = client.MakeBucket(ctx, "my-bucket", minio.MakeBucketOptions{})
if err != nil {
log.Fatal(err)
}
}
PutObject 上传失败的三个高频原因
上传卡住、返回 EOF、或提示 SignatureDoesNotMatch，往往不是代码写错，而是底层细节没对齐。
- 传入的
reader必须能重复读（比如bytes.NewReader），若用os.File且未Seek(0, 0)，第二次上传就会读到 EOF -
contentType参数不能为空字符串，否则 MinIO 可能拒绝（尤其在启用严格 MIME 检查时），建议设为"application/octet-stream"或根据文件推断 - 时间不同步会导致签名失效：
SignatureDoesNotMatch很可能是客户端系统时间与 MinIO 服务端偏差 >15 分钟，需校准 NTP
示例（安全上传）：
_, err := client.PutObject(ctx, "my-bucket", "data.json", bytes.NewReader(data), int64(len(data)), minio.PutObjectOptions{
ContentType: "application/json",
})
if err != nil {
log.Fatal(err)
}
如何安全地复用 MinIO 客户端实例
MinIO 客户端不是 goroutine-safe 的“单例”，但也不该每次请求都新建——它内部维护了 HTTP 连接池和凭证缓存，频繁重建会耗尽文件描述符或触发 429 错误。
- 全局复用一个
*minio.Client实例即可，它本身是线程安全的 - 不要在 handler 里调用
client.TraceOn（仅调试用），它会开启日志锁，高并发下严重拖慢性能 - 如果用了自定义
http.Client（比如加了 timeout），必须确保Transport支持复用连接（默认的http.DefaultTransport是 OK 的）
真正容易被忽略的是：MinIO 客户端不会自动刷新临时凭证（如 STS token）。如果你用 credentials.IAM 或 WebIdentity，必须自己实现定期刷新逻辑，否则一小时后所有请求开始 403。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
