minio客户端初始化失败主因是endpoint、accesskey、secretkey配置错误及context超时缺失；endpoint须省略协议头，accesskey/secretkey需与minio环境变量严格一致，大文件上传须传带超时的context并确认bucket存在。
MinIO 客户端初始化失败：endpoint、accessKey、secretKey 配置对不上
Go 应用连不上 MinIO，十有八九是 minio.New 初始化时参数没对齐。本地 MinIO 默认跑在 http://localhost:9000，但 Go SDK 默认要求 HTTPS；如果启用了 TLS 就得传 secure: true，否则必须显式设为 secure: false。
常见错误现象：Unable to initialize MinIO client: Invalid argument: endpoint cannot be empty 或 Connection refused —— 其实不是端口错，是协议不匹配。
-
endpoint不能带http://或https://前缀（SDK 会自己拼），只写localhost:9000或minio.example.com:9000 -
accessKey和secretKey必须和 MinIO 启动时传的环境变量完全一致（大小写敏感，空格也不行） - 若 MinIO 启用了 root 用户以外的用户策略，要确认该用户有
s3:GetObject、s3:PutObject等对应权限
上传文件卡住或报错：context 超时 + multipart 上传未处理
用 client.PutObject 上传大文件时，容易卡死或返回 context deadline exceeded，不是网络问题，而是没传合理的 context.Context，或者忽略了 MinIO 对 multipart 的隐式行为。
MinIO Go SDK 在文件 > 5MiB 时自动切分 multipart 上传，但默认 context 没设超时，底层 HTTP 连接可能等很久才失败；同时，如果服务端没开 bucket 版本控制或配了错误的存储类，也会卡在 InitiateMultipartUpload 步骤。
立即学习“go语言免费学习笔记（深入）”；
- 务必传带超时的 context：
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) - 上传前先用
client.BucketExists确认 bucket 存在，避免因 bucket 不存在导致 multipart 初始化失败静默卡住 - 小文件（minio.PutObjectOptions{ContentType: "image/png"} 不影响，但大文件建议显式设
partSize（如64 * 1024 * 1024）避免默认 5MiB 分片在弱网下频繁重试
预签名 URL 失效快：时间戳精度与服务器时钟偏差
调用 client.PresignedGetObject 生成的链接几分钟就 403，不是签名错，大概率是 Go 服务和 MinIO 服务器系统时间不同步，或预签名时用了本地 time.Now() 但没考虑时区。
MinIO 校验 presigned URL 里的 X-Amz-Date 和服务器当前时间差是否超过 15 分钟（默认），只要偏差超限就拒掉。Docker 容器里尤其常见 host 和容器时间不同步。
- 生成 URL 时统一用 UTC 时间：
time.Now().UTC()，别用time.Now().Local() - 预签名有效期（
expiresIn）别设太长，比如 24h 是安全上限；超过这个值 MinIO 可能直接忽略 - 检查 MinIO 容器是否挂载了 host 的
/etc/timezone或用了--privileged同步时钟，更稳妥的是在启动 MinIO 时加--time-sync参数（v2023+ 支持）
并发上传出错：复用同一个 minio.Client 实例就行，别每次 new
看到 goroutine 多就以为要每个请求 new 一个 minio.Client，结果内存暴涨、fd 耗尽，甚至出现 too many open files。其实 minio.Client 是线程安全的，内部自带连接池和重试逻辑，全局复用一个实例才是正确姿势。
错误做法：在 HTTP handler 里每次调 minio.New(...)；正确做法是应用启动时初始化一次，注入到 handler 或 service 结构体里。
- Client 初始化后，它的
httpClient默认用http.DefaultClient，但建议自定义：设置Timeout、MaxIdleConns、MaxIdleConnsPerHost避免连接堆积 - 不要手动调
client.TraceOn上线环境，它会记录所有请求/响应体，极易 OOM - 如果用 Wire / Dig 做依赖注入，把
*minio.Client当作 singleton 绑定，别用 transient
MinIO 的 Go SDK 表面简单，但时钟、上下文、复用这三块最容易在线上抖动——尤其是跨云厂商部署时，NTP 同步延迟和容器时区配置经常被当成“玄学问题”拖一周才定位到。
