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规范，否则后端收不到文件字段。
立即学习“Java免费学习笔记（深入）”；
- 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配置、前后端约定这三块对齐，上传下载功能就能稳稳跑起来。
