当前位置：首页 > news >正文

`commons-fileupload` 是 Apache 提供的经典 Java Web 文件上传组件，依赖 commons-io 提供IO工具方法

news 2026/8/5 11:24:36

commons-fileupload是 Apache 提供的经典 Java Web 文件上传组件，依赖 commons-io提供IO工具方法，二者配套使用，用于 Servlet 传统项目实现multipart/form-data方式文件上传。

适用场景：原生Servlet、SSM老项目（SpringMVC出现之前主流上传方案）
SpringMVC底层早期也是封装该组件：CommonsFileUploadSupport

二、Maven依赖

<!-- 文件上传核心包 --><dependency><groupId>commons-fileupload</groupId><artifactId>commons-fileupload</artifactId><version>1.5</version></dependency><!-- IO工具依赖，fileupload必须依赖它 --><dependency><groupId>commons-io</groupId><artifactId>commons-io</artifactId><version>2.16.1</version></dependency>

三、核心API

ServletFileUpload：上传解析入口
DiskFileItemFactory：文件工厂，配置临时文件、内存阈值
FileItem：封装表单字段（普通参数/上传文件）
- isFormField()判断是否普通文本参数
- getName()获取上传文件名
- getInputStream()获取文件流
- write(File dest)保存文件

四、最简代码示例（原生Servlet）

// 1. 创建工厂DiskFileItemFactoryfactory=newDiskFileItemFactory();// 设置内存临界值：超过该大小写入临时磁盘factory.setSizeThreshold(1024*1024);// 指定临时目录factory.setRepository(newFile("D:/temp"));// 2. 创建上传解析器ServletFileUploadupload=newServletFileUpload(factory);// 限制单个文件最大、总上传大小upload.setFileSizeMax(10*1024*1024);upload.setSizeMax(50*1024*1024);try{// 解析请求，得到所有表单项List<FileItem>itemList=upload.parseRequest(request);for(FileItemitem:itemList){if(!item.isFormField()){// 文件StringfileName=item.getName();item.write(newFile("D:/upload/"+fileName));}else{// 普通表单参数Stringname=item.getFieldName();Stringvalue=item.getString("UTF-8");}}}catch(Exceptione){e.printStackTrace();}

五、重要注意事项

请求头要求
前端表单必须：enctype="multipart/form-data"，否则组件无法解析。

<formmethod="post"enctype="multipart/form-data"><inputtype="file"name="file"></form>

编码问题
解析普通参数时建议指定编码item.getString("UTF-8")，防止中文乱码。
和SpringMVC关系
SpringMVC 提供CommonsMultipartResolver，内部就是封装这套API；
SpringBoot 2.x 默认使用StandardServletMultipartResolver（Servlet3.0内置上传，不需要这两个包），新项目不推荐引入 commons-fileupload。
优缺点
✅ 兼容老旧Servlet容器、灵活可控
❌ 需要手动处理临时文件清理；Servlet3.0之后有原生方案可替代；不再是首选方案