SpringBoot文件上传下载教程

本文深入剖析了Spring Boot中文件上传下载的常见陷阱与最佳实践：直击400错误和空指针根源——并非代码逻辑错误，而是Tomcat默认1MB上传限制、@RequestParam误用于MultipartFile（必须改用@RequestPart）、前端手动设置Content-Type破坏boundary解析；同时强调安全存储关键点：严格校验文件名防路径遍历、生成唯一UUID文件名、写入独立可控目录而非Web根路径，并规避InputStream重复读取问题；下载方案也给出轻量级ResponseEntity与流式OutputStream的适用边界，助你一次写出稳定、安全、可维护的文件处理模块。

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还是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重要得多。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《SpringBoot文件上传下载教程》文章吧，也可关注golang学习网公众号了解相关技术文章。