MinIO Go客户端连不上主因是endpoint与Secure配置不匹配：本地开发需用"localhost:9000"且Secure设为false；NoSuchBucket错误源于未调用MakeBucket显式创建桶，且桶名须全小写、3–63字符、不含下划线或IP格式。
MinIO Go 客户端连不上，八成是 endpoint 协议/端口和 Secure 配置对不上；上传报 NoSuchBucket 不是服务问题，而是没调 MakeBucket —— 这两个坑踩过一次，后面基本就稳了。
minio.New 初始化失败：endpoint 和 Secure 必须严格匹配
本地开发时，MinIO 默认跑在 http://localhost:9000，但 minio-go/v7 默认启用 TLS 校验。如果传入 "localhost:9000"（缺协议）或 "https://localhost:9000"（协议错），客户端会尝试 HTTPS 握手，结果卡住或 panic 报 x509: certificate signed by unknown authority。
- 本地开发：用
minio.New("localhost:9000", "minioadmin", "minioadmin", false)，第四个参数显式设为false，且endpoint不带http://或https:// - 生产环境：endpoint 必须是域名（如
s3.internal），且第四个参数为true，同时确保系统信任该域名证书（或手动注入到http.DefaultTransport.TLSClientConfig.RootCAs） - 调试前先确认服务通：运行
curl -v http://localhost:9000/minio/health/live，返回 200 再写代码
PutObject 报 NoSuchBucket：桶必须显式创建
MinIO 的 PutObject 不会自动建桶，行为和 AWS S3 一致。错误不是“找不到桶”，而是“你根本没创建过”。直接调用会导致 NoSuchBucket 错误，且不会提示“请先建桶”。
- 必须提前调
client.MakeBucket(ctx, bucketName, minio.MakeBucketOptions{Region: "us-east-1"}) - 检查错误是否为
minio.ErrBucketAlreadyOwnedByYou—— 这个错误可安全忽略，表示桶已存在 - 桶名必须全小写、3–63 字符、不含下划线或大写字母、不能是 IP 格式（如
192.168.1.1） - 如果
MakeBucket指定了Region，后续所有操作（包括PutObject）都得用同一 region，否则某些 MinIO 版本会静默失败
上传大文件卡死或 OOM：别把整个文件读进内存
用 bytes.NewReader(data) 或 strings.NewReader(content) 传给 PutObject，等于把全部内容加载到内存再分块上传。100MB 文件可能吃掉 300MB+ 内存，还容易触发 context deadline exceeded。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
- 大文件一律用
*os.File：f, _ := os.Open("large.zip")，确保句柄有效且未关闭 - 必须传带超时的 context：
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)，再传给PutObject - 如需调整分块大小（默认 5MB），用
minio.PutObjectOptions{PartSize: 10 * 1024 * 1024}，避免小文件上传时 HTTP 请求过多
GetObject 返回空数据：别跳过 error 检查和 body 关闭
GetObject 成功返回 resp *minio.Object 并不意味着对象存在——它只表示 HTTP 请求发出去了。如果对象不存在或权限不足，MinIO 可能返回 404/403 状态码，但 SDK 有时不转成 Go error，resp.ContentLength 就是 0，io.Copy 写出来就是空文件。
- 务必检查
err：哪怕resp != nil，也要看err != nil - 用
defer resp.Close()，否则连接池耗尽后后续请求全卡住 - 下载前可先用
StatObject验证对象是否存在：client.StatObject(ctx, bucket, object, minio.StatObjectOptions{})
真正难的不是 API 调用，而是那些不报错却悄悄失效的点：桶名规则、region 一致性、reader 生命周期、TLS 配置粒度。这些地方一旦出错，日志里往往只有一行模糊的 context canceled 或空响应，得靠经验快速定位。
