MinIO连接失败主因是协议、端口、TLS配置未对齐：endpoint须含协议和端口（如"http://localhost:9000"），MinIO 8.0+默认强制TLS，本地开发需显式设Secure:false，AccessKey/SecretKey须与MINIO_ROOT_USER/PASSWORD严格一致，初始化后应立即调用ListBuckets验证连通性。
直接用 minio-go/v7 或 aws-sdk-go-v2 就行，别绕路写底层 HTTP 请求——两者都已封装签名、重试、分块上传等逻辑，硬啃 S3 REST API 是典型的时间陷阱。
minio-go/v7 连接本地 MinIO 为什么连不上？
根本原因不是代码写错，而是协议、端口、TLS 配置三者没对齐。
-
endpoint必须带协议和端口，比如"http://localhost:9000"，不能只写"localhost:9000"或漏掉:9000 - MinIO 8.0+ 默认强制 TLS，本地开发没证书时，必须显式传
minio.Options{Secure: false}，否则卡在握手阶段 - AccessKey/SecretKey 要和启动 MinIO 时的
MINIO_ROOT_USER/MINIO_ROOT_PASSWORD完全一致，大小写敏感 - 客户端初始化后，立刻调用
client.ListBuckets或client.MakeBucket测试连通性，别等上传时才暴露问题
aws-sdk-go-v2 初始化 client 时 region 怎么配才不超时？
region 错配是 s3.PutObject 超时的第一大原因，SDK 不报错，只默默走 global endpoint 导致跨域延迟飙升。
- 先查真实 bucket region：
aws s3api get-bucket-location --bucket your-bucket-name（注意：us-east-1 返回空字符串，要按逻辑视为us-east-1） - 初始化 config 时必须显式传
config.WithRegion("your-region")，别依赖环境变量或配置文件自动推断 - 国内用户用 AWS CN 区域（如
cn-north-1），必须同时设config.WithEndpointResolverWithOptions指向https://s3.cn-north-1.amazonaws.com.cn - 如果用 MinIO 或其他 S3 兼容服务，
region可填任意非空字符串（如"us-east-1"），但endpoint必须准确，且config.WithRegion仍需传值，否则 SDK 可能 panic
上传大文件时内存暴涨或 context deadline exceeded 怎么办？
s3.PutObject 和 minio.Client.PutObject 都不是真正流式——它们内部会尝试读取全部 body 计算 checksum 和签名，尤其当没设 ContentLength 时更危险。
立即学习“go语言免费学习笔记（深入）”；
- 文件 >5MB，优先用
s3manager.Uploader（AWS）或minio.PutObjectWithContext+ 显式ContentLength（MinIO） - 传
*os.File给PutObject前，务必先stat获取 size，填入ContentLength字段；bytes.Reader不支持Seek，会导致 SDK 全读进内存 - MinIO 服务端 multipart 阈值默认 5MB，低于该值走单次 PUT；若想强制分块上传，MinIO 需用
minio.PutObjectOptions设置ContentType和NumThreads，AWS 则交给s3manager.Uploader自动处理 - 永远给上传操作加
context.WithTimeout，别用全局 context，超时时间至少设为文件大小 × 2 秒（例如 100MB 设 3 分钟）
GetObject 返回空 body 或 NoSuchKey，但控制台能看见文件
几乎全是 key 编码或路径前缀问题，S3 的 key 是纯字符串，不解析为目录结构，SDK 却默认做 URL 编码，而控制台显示的是解码后的结果。
- 用
s3.HeadObject或minio.Client.StatObject先验证 key 是否存在，绕过 SDK 编码逻辑 - 检查 key 变量是否有多余前导
/（如"/logs/app.log"→ 应为"logs/app.log"）；拼接时用path.Join后strings.TrimPrefix - key 来自用户输入（如文件名含中文、空格、+）时，必须手动
url.PathEscape再传给 SDK；不要依赖 SDK 自动编码，行为不一致 - listObjectsV2 返回的
Contents.Key是原始值，别二次url.PathEscape，否则查不到
最易被忽略的是：MinIO 的 MakeBucket 不自动建父级路径，也不静默失败；AWS 的 PutObject 不自动建桶，错误类型还和权限混淆（NoSuchBucket vs AccessDenied）。这两处不加显式判断，线上一跑就挂。
