MinIO连接失败主因是服务未启动或监听地址错误；默认仅监听localhost:9000，需用--address显式绑定IP；客户端endpoint须为完整无路径URL；bucket需显式创建且命名合规；Spring Boot需统一OkHttp版本。
MinIO服务端启动后连不上，Connection refused 是最常见的错觉
不是客户端配错了，大概率是 MinIO 根本没跑起来，或者监听地址不对。默认启动命令 minio server ./data 只监听 localhost:9000，而 Java 客户端如果用 http://127.0.0.1:9000 或 http://localhost:9000 通常能通；但一旦换成 http://0.0.0.0:9000 或宿主机 IP（比如 http://192.168.1.10:9000），Java 客户端就可能被拒绝——因为 MinIO 默认不绑定到所有接口。
解决方法很简单：
- 启动时显式指定地址：
minio server --address :9000 ./data（注意--address :9000表示监听所有 IPv4 接口） - 或更安全地绑定到具体网卡：
minio server --address 192.168.1.10:9000 ./data - 确认端口没被占用：
lsof -i :9000（macOS/Linux）或netstat -ano | findstr :9000（Windows） - 防火墙要放行 9000 端口，尤其在 Windows 或某些 Linux 发行版上容易忽略
Java 客户端初始化报 InvalidEndpointException：URL 格式和协议必须严格匹配
MinIO 要求 endpoint 必须是完整 URL，且不能带路径后缀（比如不能是 http://localhost:9000/minio），也不能漏掉协议。常见错误写法："localhost:9000"、"http://localhost:9000/"（末尾斜杠）、"https://localhost:9000"（但服务端没开 TLS）。
正确初始化方式（以 minio-java 8.5+ 为例）：
立即学习“Java免费学习笔记（深入）”；
MinioClient client = MinioClient.builder()
.endpoint("http://localhost:9000") // 必须是完整 http/https URL，无路径，无尾部斜杠
.credentials("minioadmin", "minioadmin") // 默认账号密码，可改
.build();
注意点：
-
endpoint字符串里不能有空格、制表符或不可见 Unicode 字符（复制粘贴时容易中招） - 如果 MinIO 启用了 TLS（比如用
minio server --certs-dir），那 endpoint 必须用https://，且 JVM 需信任对应证书，否则会抛SSLHandshakeException - MinIO 8.0+ 默认关闭了 S3 兼容的
path-style访问，Java 客户端无需额外配置enablePathStyleAccess(true)，加了反而可能出问题
上传文件后控制台看不到 Bucket，listBuckets() 返回空列表
这不是权限或连接问题，而是 MinIO 的 bucket 创建机制和 AWS S3 不同：它不会自动创建 bucket，必须显式调用 makeBucket，而且 bucket 名必须全小写、不含下划线、符合 DNS 兼容格式（如 my-test-bucket 合法，MyTestBucket 或 test_bucket 会失败）。
典型操作顺序：
client.makeBucket(MakeBucketArgs.builder().bucket("my-test-bucket").build());
client.putObject(PutObjectArgs.builder()
.bucket("my-test-bucket")
.object("hello.txt")
.stream(new ByteArrayInputStream("hello".getBytes()), 5, -1)
.build());
容易踩的坑：
- 用中文或特殊字符命名 bucket（MinIO 拒绝，但错误信息模糊，常表现为
ErrorResponseException: The specified bucket does not exist） - 误以为上传对象会自动建 bucket（AWS CLI 的
aws s3 cp会隐式创建，但 MinIO Java SDK 不会） - 测试时反复运行代码却没清理 bucket，导致
makeBucket报BucketAlreadyExistsException—— 这是正常行为，不是错误，可捕获忽略或先listBuckets判断
Spring Boot 项目里集成 MinIO，MinioClient Bean 初始化失败
最常见原因是依赖版本冲突：Spring Boot 2.x 默认带旧版 OkHttp（3.x），而 minio-java 8.x 要求 OkHttp 4.9+；若项目里又引了其他依赖（如 Retrofit、Feign）间接拉入低版本 OkHttp，就会在构造 MinioClient 时抛 NoClassDefFoundError: okhttp3/OkHttpClient$Builder。
稳妥做法：
- 强制升级 OkHttp：
implementation 'com.squareup.okhttp3:okhttp:4.12.0'（与 minio-java 8.5+ 兼容） - 排除传递依赖：
configurations.all { exclude group: 'com.squareup.okhttp3', module: 'okhttp' } - 避免用
@Bean手动 newMinioClient，改用 Builder 构造，确保内部 HTTP client 被正确初始化 - 别把 MinIO 配置硬编码进
@Bean方法——抽到@ConfigurationProperties类里，方便测试环境切换 endpoint 和凭据
本地测试环境最省事的组合：MinIO 服务用 Docker 启动（docker run -p 9000:9000 -p 9001:9001 quay.io/minio/minio server /data --console-address :9001），Java 端用 http://localhost:9000 + 默认账号，其余全走 builder 配置。复杂点在于 TLS 和多节点部署，但本地测试真用不到。
