minio go客户端连接失败主因是协议/端口不匹配、tls配置错误或凭据不符；需严格匹配endpoint协议、显式设置secure=false（本地无证书时）、校验accesskey/secretkey一致性；操作前须调用makebucket并处理errbucketalreadyownedbyyou；上传大文件应使用带timeout的putobjectwithcontext及可seek的reader；listobjectsv2需正确设置prefix（如"logs/"）和delimiter="/"，并手动处理分页。
MinIO服务启动后无法通过Go客户端连接
常见现象是 minio.New 返回 Connection refused 或 context deadline exceeded，本质是网络通路或认证配置没对上。MinIO默认监听 9000 端口，但 Go 客户端若用 HTTPS 访问却连了 HTTP 地址，或反过来，必然失败。
- 确认 MinIO 启动时是否加了
--address :9000（HTTP）或--address :9001 --console-address :9002并配了 TLS；Go 客户端的 endpoint 必须严格匹配协议+端口，比如"http://localhost:9000"不能写成"localhost:9000" - MinIO 8.0+ 默认启用强制 TLS，本地开发若没配证书，得在客户端显式关闭 SSL 验证：
minio.Options{Secure: false}，否则会卡在 TLS 握手 - AccessKey/SecretKey 必须和 MinIO 启动时指定的一致（如用
MINIO_ROOT_USER和MINIO_ROOT_PASSWORD），Go 客户端传参顺序不能颠倒：minio.New(endpoint, accessKey, secretKey, secure)
用 minio-go v7 写文件时提示 “NoSuchBucket”
不是桶不存在，而是客户端没提前创建，且 PutObject 默认不自动建桶——这和 AWS S3 行为一致，但很多人误以为像本地文件系统一样“路径不存在就自动 mkdir”。
- 必须先调用
MakeBucket，且要检查返回错误是否为minio.ErrBucketAlreadyOwnedByYou，这个错误表示桶已存在，可安全忽略 - MinIO 的桶名有严格规则：全小写、不能含下划线、长度 3–63 字符、不能是 IP 格式；传错名字会导致
MakeBucket失败，但错误信息模糊，容易误判 - 如果用
MakeBucket时指定了 region（如"us-east-1"），后续所有操作都得用同一 region，否则某些版本会静默失败
上传大文件时内存暴涨或超时
PutObject 默认把整个 io.Reader 读进内存再分块上传，对 >100MB 的文件极易 OOM 或触发 context timeout。
- 改用
PutObjectWithContext并传入带 timeout 的context.Context，比如context.WithTimeout(ctx, 5*time.Minute) - 确保传入的 reader 是流式（如
os.Open文件句柄），不要用bytes.NewReader(data)加载全部内容到内存 - MinIO 服务端默认 multipart 上传阈值是 5MB，低于该值走单次 PUT；若想强制分块，可用
minio.PutObjectOptions{NumThreads: 3}控制并发上传线程数，但注意 NumThreads > 1 时必须保证 reader 可 seek（*os.File可以，bytes.Reader不行）
ListObjectsV2 返回空结果但实际有文件
最常踩的坑是 prefix 和 delimiter 搞混，或没处理分页。MinIO 兼容 S3 V2 列表接口，但 Go SDK 的 ListObjectsV2 默认只返回前 1000 个，且 prefix 匹配逻辑和本地路径直觉不同。
立即学习“go语言免费学习笔记（深入）”；
- prefix 是“开头匹配”，不是“目录匹配”；例如桶里有
logs/app-2024-01.log，想查 logs/ 下所有文件，prefix 得设为"logs/"（结尾带斜杠），否则"logs"会匹配到logs-bak/这类名字 - 如果想模拟“列出子目录”，需配合
delimiter: "/"，此时响应里的CommonPrefixes字段才有效；不设 delimiter 就只能靠 prefix + 自己解析 key 路径 - 务必检查
IsTruncated字段，为 true 时要用NextContinuationToken继续调用，SDK 不自动翻页
MinIO 的 S3 兼容性整体很稳，但 Go 客户端对错误码的封装比较薄，很多底层 HTTP 错误直接透出，得自己查 minio.ToErrorResponse(err) 才能拿到真实 S3 错误码。别依赖 error.String() 做判断。
