Java项目中MinIO使用超全流程(含完整示例)
更新时间：2026年04月14日 08:16:49 作者：章鱼哥730
MinIO是全球领先的对象存储先锋,目前在全世界有数百万的用户,这篇文章主要介绍了Java项目中MinIO使用的相关资料,文中通过代码介绍的非常详细,需要的朋友可以参考下
一、前言
在现代微服务架构中，文件存储 是非常常见的业务场景。
传统的文件存储（比如本地磁盘、FTP）已经无法满足高可用、高扩展的需求。
这时候，对象存储系统（Object Storage） 就成为了首选方案，而 MinIO 是其中最轻量、最易用、且兼容 S3 协议的解决方案之一。
本文将带你从零开始，使用 Java（尤其是 Spring Boot 项目）集成 MinIO，实现：
✅ 文件上传与下载
✅ 文件预览链接生成
✅ 判断文件是否存在
✅ 删除文件
二、MinIO 简介
MinIO 是一个高性能、分布式对象存储服务，支持 S3 API，可以轻松部署在本地或云服务器上。
无论是文件存储、AI 训练数据、日志归档、图片/视频等，都非常适用。
特点
100% 兼容 Amazon S3 API
支持本地部署
高性能（可达 NAS 的吞吐）
开源免费
三、引入依赖
在 pom.xml 中添加以下依赖：
<dependency>
<groupId>io.minio</groupId>
<artifactId>minio</artifactId>
<version>8.5.10</version>
</dependency>⚠️ 建议使用 8.x+ 版本，API 更现代，支持
try-with-resources自动关闭流。
四、配置 MinIO 连接信息
在你的 application.yml 中加入以下配置：
minio: endpoint: http://127.0.0.1:9000 access-key: admin secret-key: 12345678 bucket-name: my-bucket
五、编写配置类
import io.minio.MinioClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class MinioConfig {
@Value("${minio.endpoint}")
private String endpoint;
@Value("${minio.access-key}")
private String accessKey;
@Value("${minio.secret-key}")
private String secretKey;
@Bean
public MinioClient minioClient() {
return MinioClient.builder()
.endpoint(endpoint)
.credentials(accessKey, secretKey)
.build();
}
}六、封装工具类（核心代码）
import io.minio.*;
import io.minio.errors.*;
import io.minio.http.Method;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import org.springframework.web.multipart.MultipartFile;
import java.io.InputStream;
import java.util.concurrent.TimeUnit;
@Component
public class MinioUtil {
private final MinioClient minioClient;
@Value("${minio.bucket-name}")
private String bucketName;
public MinioUtil(MinioClient minioClient) {
this.minioClient = minioClient;
}
/** 上传文件 **/
public String upload(MultipartFile file) throws Exception {
String fileName = System.currentTimeMillis() + "_" + file.getOriginalFilename();
try (InputStream inputStream = file.getInputStream()) {
minioClient.putObject(
PutObjectArgs.builder()
.bucket(bucketName)
.object(fileName)
.stream(inputStream, file.getSize(), -1)
.contentType(file.getContentType())
.build()
);
}
return fileName;
}
/** 获取文件访问URL **/
public String getFileUrl(String fileName) throws Exception {
return minioClient.getPresignedObjectUrl(
GetPresignedObjectUrlArgs.builder()
.method(Method.GET)
.bucket(bucketName)
.object(fileName)
.expiry(7, TimeUnit.DAYS)
.build()
);
}
/** 删除文件 **/
public void remove(String fileName) throws Exception {
minioClient.removeObject(
RemoveObjectArgs.builder()
.bucket(bucketName)
.object(fileName)
.build()
);
}
/** 判断文件是否存在 **/
public boolean exists(String fileName) {
try {
minioClient.statObject(
StatObjectArgs.builder()
.bucket(bucketName)
.object(fileName)
.build()
);
return true;
} catch (Exception e) {
return false;
}
}
}七、Controller 示例
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import lombok.RequiredArgsConstructor;
@RestController
@RequestMapping("/file")
@RequiredArgsConstructor
public class FileController {
private final MinioUtil minioUtil;
@PostMapping("/upload")
public String upload(@RequestParam MultipartFile file) throws Exception {
return minioUtil.upload(file);
}
@GetMapping("/url/{fileName}")
public String getUrl(@PathVariable String fileName) throws Exception {
return minioUtil.getFileUrl(fileName);
}
@DeleteMapping("/{fileName}")
public void delete(@PathVariable String fileName) throws Exception {
minioUtil.remove(fileName);
}
}八、常见问题与优化建议
1、上传大文件时报错？
MinIO 默认分片上传上限为 5GB。超过建议使用 分片上传 API 或者配置 Nginx 转发大文件。
2、中文文件名乱码？
可在上传时 URLEncoder.encode(fileName, "UTF-8")。
3、安全性考虑
上传时可自定义路径前缀（如
userId/xxx.png）；下载使用
getPresignedObjectUrl临时签名，而非公开 URL；不建议让前端直接知道
accessKey/secretKey。
九、实战建议
✅ 将上传逻辑抽象为
FileService接口，方便后续替换为 OSS、COS 等云服务。✅ 对 URL 做缓存（比如 Redis）减少签名生成压力。
✅ 搭配 Nginx 做静态文件反代，更安全更快。
✅ 日志中不要输出 accessKey。
结语
MinIO 是一款轻量级、高性能的对象存储系统，非常适合在 Java / SpringBoot 项目中快速接入。
无论是内部文档管理、AI 训练数据、还是企业文件中台，它都能胜任。
相关文章
这篇文章主要介绍了springboot文件打包成jar或war的方法以及相关知识点，需要的朋友们参考下。2019-08-08
SpringSecurity是一个功能强大的安全框架,提供了全面的 Web 安全功能,它的核心之一是过滤器链,用于拦截和处理 Web 请求,本文就来介绍SpringSecurity配置和使用过滤器来管理Web请求的安全性,感兴趣的可以了解一下2025-09-09
我们使用Java导出图片到Excel,打开成功导出的Excel一看,商品对应的图片都很规矩的按照我的设置铺满了整个单元格,但是,商品图片却都变形了,这样肯定是不行的,于是第一反应就是将图片等比例导出,所以本文本给大家介绍了如何使用Java Web导出等比例图片到Excel2023-11-11
OOM是JVM抛出的错误,表示内存分配失败,这篇文章主要介绍了线上Java OOM问题定位与解决方案的相关资料,文中通过代码介绍的非常详细,需要的朋友可以参考下2025-09-09
在Web应用中,Token用于身份验证和会话管理,但当Token过期时,可能会导致用户在提交表单或进行操作时突然被重定向到登录页面,本文就来介绍一下java实现token无感刷新+处理并发的后端方案,感兴趣的可以了解一下2024-11-11
URI与URL的区别 一.先来序言一段 二.协议的自定义的理解 三.自定义协议与URL的关系 四.URL自定义私有协议实战 五.后话，自定义mineType解析器2016-04-04
这篇文章主要介绍了Java eclipse doc文档生成流程解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2020-12-12
使用@Autowired注解警告Field injection is not recommended的解决
这篇文章主要介绍了使用@Autowired注解警告Field injection is not recommended的解决，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2020-04-04
Spring中BeanFactory和ApplicationContext的作用和区别(推荐)
这篇文章主要介绍了Spring中BeanFactory和ApplicationContext的作用和区别,本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下2020-09-09
基于SpringBoot和Vue3的博客平台的用户注册与登录功能实现
本教程将指导您如何使用Spring Boot和Vue3实现用户注册与登录功能。我们将使用Spring Boot作为后端框架，Vue3作为前端框架，同时使用MySQL作为数据库，感兴趣的朋友可以参考一下2023-04-04
最新评论