必须确认三件事：一是Go版本≥1.18并显式安装minio-go/v7；二是MinIO服务端启用Signature V4且endpoint协议与Secure参数严格匹配；三是PutObject必须传带timeout的context，避免默认5秒超时导致失败。
Go 语言调用 MinIO SDK 前必须确认的三件事
MinIO 官方 SDK minio-go 是 Go 生态中最稳定、最贴近 S3 协议的客户端，但直接 import 就跑不起来——常见报错如 cannot find package "github.com/minio/minio-go/v7" 或运行时报 signature does not match，往往源于基础配置没对齐。
- 确认 Go 版本 ≥ 1.18（
v7起要求模块化支持，低版本会卡在依赖解析） - 使用
go get github.com/minio/minio-go/v7@latest显式安装，别依赖go mod tidy自动推导——v7 和 v6 的 API 差异大，自动降级会导致MakeBucket等方法找不到 - MinIO 服务端必须启用 Signature V4（默认开启），但若自行部署时用了旧版镜像（如
minio/minio:RELEASE.2022-10-29T01-11-20Z），需检查MINIO_SERVER_URL是否含端口且协议明确（http://或https://），否则 SDK 默认走 HTTPS 会握手失败
上传文件时 PutObject 报 context deadline exceeded 怎么快速定位
这不是网络超时那么简单。Go SDK 的 PutObject 默认带 5 秒上下文超时，而 MinIO 在小文件（
- 先加日志：用
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)替换默认上下文，再看是否仍失败 - 如果仅大文件失败，检查 MinIO 服务端磁盘空间和 inode 使用率（
df -i），纠删码模式下写入需预留校验块空间，空间不足时会静默卡住而非报错 - 确认对象 key 不含非法字符（如
\、CR/LF），MinIO 对 key 的 UTF-8 校验比 AWS S3 更严格，错误 key 会导致签名计算异常，表现为超时
如何让 Go 程序安全地复用 MinIO Client 实例
minio.Client 是线程安全的，但错误复用方式会导致连接池耗尽或凭证失效。典型现象是并发上传时部分请求返回 403 Forbidden 或 connection refused。
- 全局只初始化一次 client：在
init()或 main 包变量中创建，传参用&minio.Options{Creds: credentials.NewStaticV4(...), Secure: false} - 不要每次请求都 new client——SDK 内部维护 HTTP 连接池，频繁重建会触发 TCP TIME_WAIT 暴增，Linux 默认 65536 端口很快耗尽
- 若需切换不同 MinIO 实例（如 dev/staging），用 map 缓存 client：
clients["dev"] = client，避免重复 dial
MinIO 本地开发时，为什么 GetObject 返回空数据但 HTTP 状态码是 200
这通常不是 Go 代码问题，而是 MinIO 的 bucket policy 或 object ACL 配置被忽略。UI 界面里点“readonly”规则只作用于浏览器直链访问，不影响 SDK 调用。
立即学习“go语言免费学习笔记（深入）”；
- SDK 默认走 IAM 认证，哪怕你用 root 凭证，也要确保该用户有
s3:GetObject权限（通过mc admin user add或策略 JSON 绑定） - 检查 bucket 是否启用了 versioning：若对象被覆盖过，
GetObject默认读最新版本，但若你上传时没设x-amz-metadata-directive: REPLACE，旧元数据可能残留导致 Content-Length 为 0 - 最简验证法：用
mc cp命令行下载同一对象，若成功则说明是 Go 侧io.Copy或 buffer 处理问题；若也失败，就是服务端权限或对象本身损坏
mc event）而不是轮询，而这个机制依赖 Redis 或 NATS，一环断就全链路静默失败。 
