根本原因是Tomcat默认文件上传限制及注解误用：MultipartFile必须用@RequestPart而非@RequestParam，且需在application.yml中配置max-file-size和max-request-size；前端勿手动设置Content-Type；存储时须校验文件名、生成唯一路径并避免直接写Web根目录。
Spring Boot里用MultipartFile接收文件，为什么总报400或空指针？
根本原因不是代码写错了，而是默认的Servlet容器（Tomcat）对文件上传有硬性限制，且@RequestParam和@RequestPart语义不同，混用就会失败。
-
MultipartFile必须用@RequestPart注解，不能用@RequestParam——后者只适合简单类型，Spring 5+之后对@RequestParam处理MultipartFile已明确弃用 - 默认单文件大小上限是1MB，超过就直接返回400，不进控制器；需在
application.yml里显式配置：spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MB - 如果前端用
fetch或axios发请求，Content-Type别手动设为multipart/form-data——浏览器会自动加boundary，手设反而导致解析失败
怎么把MultipartFile安全存到磁盘或云存储？
别直接调transferTo()写到Web根目录下，路径不可控、权限难管、重启可能丢文件。重点是「分离存储逻辑」和「校验前置」。
- 先校验
isEmpty()、getOriginalFilename()是否为空或含路径遍历字符（如../），否则可能被写到任意位置 - 用
Files.createTempDirectory()或业务专用目录（如/data/uploads/），确保父目录存在且可写：Files.createDirectories(Paths.get("/data/uploads")) - 生成唯一文件名，避免覆盖或冲突：
UUID.randomUUID() + "-" + file.getOriginalFilename()，再用file.transferTo(path) - 如果存OSS/S3，别把
InputStream反复读两次——MultipartFile.getInputStream()只能读一次，要用file.getBytes()或先缓存到ByteArrayInputStream
下载文件时用ResponseEntity<Resource>还是OutputStream？
小文件（ResponseEntity更简洁；大文件或需要断点续传、动态拼接内容时，必须用HttpServletResponse.getOutputStream()手动刷数据流，否则容易OOM或超时。
-
ResponseEntity方式要配Content-Disposition头，否则浏览器可能直接渲染而不是下载：Headers headers = new HttpHeaders(); headers.add("Content-Disposition", "attachment; filename=\"" + URLEncoder.encode(filename, "UTF-8") + "\""); - 用
OutputStream时，务必设Content-Type（如application/octet-stream）和Content-Length（能提前知道大小时），否则部分浏览器无法显示进度条 - 别在Controller里用
new FileInputStream()——文件可能被其他进程锁住或已删除；优先用ResourceLoader.getResource("file:/path/to/file")或Files.newInputStream()并包裹在try-with-resources里
为什么本地调试上传正常，部署到Linux服务器就失败？
90%是路径权限和临时目录问题，和Spring Boot本身无关，但错误日志常被误读为框架异常。
- Tomcat默认用
/tmp存上传临时文件，而某些Linux发行版（如CentOS）的/tmp挂载了noexec或nosuid，导致JVM无法创建临时文件——改配置：server.tomcat.basedir=/opt/tomcat-temp - 应用用户（如
appuser）对目标存储目录没有写权限，chown -R appuser:appuser /data/uploads比chmod 777安全得多 - Nginx反向代理时没配
client_max_body_size，即使Spring Boot放开限制，Nginx仍会截断请求，返回413 —— 在nginx.conf的http或location块里加client_max_body_size 10M;
上传下载看着简单，真正卡住人的永远是容器行为、系统权限、中间件限制这三层叠加。把每层的默认值和生效位置搞清楚，比背API重要得多。
