17370845950

Java文件上传下载需匹配Servlet 3.0+与Web容器（如Tomcat 7+），Spring Boot 2.2+默认支持；关键配置包括spring.servlet.multipart.max-file-size、max-request-size；前端须用enctype="multipart/form-data"及正确name属性；常见问题有参数不匹配、流重复读取、中文名乱码等。

Java中搭建文件上传下载项目，核心是选对技术栈、配好基础环境、处理好HTTP协议细节。不是单纯引入一个库就能跑通，得从Web容器、框架支持、依赖管理、安全限制几方面一起看。

Web容器与Servlet版本要匹配

文件上传依赖Servlet 3.0+的API（如Part接口），Tomcat 7及以上默认支持；若用Tomcat 6或更老版本，必须手动集成commons-fileupload + commons-io。Spring Boot内嵌Tomcat 9时，默认已满足要求，无需额外配置。

• 检查pom.xml中spring-boot-starter-web版本，2.2+默认带Servlet 4.0
• 若独立部署，确认web.xml的web-app版本声明为3.0或更高
• 避免在application.properties里误设server.servlet.context-path=/api却忘了前端请求路径同步调整

Spring Boot项目的关键配置项

Spring Boot简化了上传逻辑，但几个关键配置漏掉就会报错“Request entity too large”或“Failed to parse multipart servlet request”。这些不是代码问题，而是配置没生效。

• spring.servlet.multipart.max-file-size=10MB（单文件上限）
• spring.servlet.multipart.max-request-size=50MB（整个请求总大小）
• spring.servlet.multipart.enabled=true（默认true，但显式写上更稳妥）
• 注意：Spring Boot 2.0+用spring.servlet.前缀，旧版用spring.http.，别混用

前后端配合要点

上传不是后端单方面的事。前端表单必须符合multipart/form-data规范，否则后端收不到文件字段。

• HTML表单加enctype="multipart/form-data"，且要有name属性（后端@RequestParam("xxx")靠它映射）
• Axios上传需设置headers: {'Content-Type': 'multipart/form-data'}——其实不用设，浏览器自动识别并生成边界（boundary），手动设反而会出错
• 下载时后端用ResponseEntity返回，前端用a.download或fetch + blob触发保存，别直接window.location.href跳转（GET长度受限，大文件失败）

常见坑与绕过方式

开发时高频报错，多数和环境或配置隐性冲突有关：

• “Required request part 'file' is not present”：前端name不匹配 / 表单没加enctype / 后端用了@RequestBody而非@RequestParam
• “Stream closed”读取Part内容两次：part.getInputStream()只能读一次，需缓存字节数组再复用
• Linux下下载中文名乱码：响应头加Content-Disposition: attachment; filename*=UTF-8''%E6%B5%8B%E8%AF%95.pdf（RFC 5987格式）
• 临时文件目录磁盘满？改spring.servlet.multipart.location=/data/tmp并确保有写权限

基本上就这些。环境配置不复杂但容易忽略细节，把Servlet版本、Spring Boot配置、前后端约定这三块对齐，上传下载功能就能稳稳跑起来。