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之后有原生方案可替代；不再是首选方案
六、版本提醒
- commons-fileupload 1.4+ 最低要求Java 8
- 不要混用高低版本 commons-io，容易出现
NoSuchMethodError
如果你需要，我可以补充：
- SpringMVC整合 CommonsFileUpload 配置
- 上传文件名去重、类型校验、异常捕获完整工具类
- 和 Servlet3.0 原生上传方案对比
