最后更新：2026-10-28
适用场景：Spring Boot 3.x、Spring MVC、multipart/form-data、Nginx 反向代理

小图片能传，大一点就报 413；把 Spring Boot 的上传限制调大后，浏览器还是失败。上传问题最怕“只改一个数字”：请求可能在 Nginx 就被拦了，也可能到了 Spring 才触发文件大小限制，甚至根本不是一个正确的 multipart 请求。

先确认是谁拒绝了请求

在浏览器 Network 里看失败请求的状态、Response Headers 和响应体，同时看应用日志与 Nginx 日志。应用没有收到请求，就先查入口代理；应用日志里有 multipart 解析异常，才回到 Spring Boot 配置。不能只根据前端弹窗里的“上传失败”判断。

用同一个小文件、同一个大文件分别测试，再直接请求应用端口（仅在可信测试环境、网络允许时）。直连成功而经域名访问报 413，问题大概率在代理或前置网关，而不是 Controller。

Spring Boot 有两道大小限制

Spring Boot 3.5 的默认值是 单个文件 1MB、整个 multipart 请求 10MB。请求里有多个文件或其他表单字段时，只调 max-file-size 还不够。比如业务允许单文件不超过 20MB，可以先这样配置：

spring:
  servlet:
    multipart:
      max-file-size: 20MB
      max-request-size: 25MB

这里的 25MB 是示例，不是通用推荐值；应按实际“最多几个文件、每个多大、额外字段多少”制定。改完确认配置被当前 profile 加载，并重启实际运行的服务。spring.servlet.multipart.* 是 Servlet MVC 的配置，若项目用的是 WebFlux，不能照抄这组参数。Spring Boot 官方属性表列出了默认值。

如果应用前面还有 Nginx，它的 client_max_body_size 也必须允许这次请求体。例如：

location /api/upload {
    client_max_body_size 25m;
    proxy_pass http://127.0.0.1:8080;
}

实际部署要结合原有 location 和 proxy_pass 规则修改，别直接复制成新的线上配置。修改后先检查配置语法，再按运维流程重载。Nginx 官方文档说明，超过 client_max_body_size 会返回 413；若还有 CDN、Ingress 或 API 网关，也要逐层核对它们的限制。Nginx 指令说明

不报 413，却拿不到 MultipartFile

这时看请求格式和字段名。一个最小接口可以写成：

@RestController
public class UploadController {
    @PostMapping("/api/upload")
    public String upload(@RequestParam("file") MultipartFile file) {
        return "bytes=" + file.getSize();
    }
}

用 curl 复现时，-F 会构造 multipart 表单：

curl -i -F 'file=@./sample.png' http://localhost:8080/api/upload

前端 FormData 的键必须叫 file，与 @RequestParam("file") 对应。不要把文件转成 JSON 发送，也别在使用 FormData 时手写没有 boundary 的 Content-Type: multipart/form-data；让浏览器设置该头。若报 Required part 'file' is not present，先看实际请求里有没有 file 这个 part，而不是继续调大大小限制。Spring Boot 的 Multipart 说明也采用 MultipartFile 参数。

上传到一半才失败，还要看临时目录

接收上传并不等于文件已经存进你的业务目录。容器会先处理 multipart 数据，较大的文件可能涉及临时目录。磁盘满、临时目录不可写、容器文件系统只读，都可能在这个阶段出问题。排查时记录异常的根因，检查服务账号的磁盘配额和临时目录权限，不要把“没到 Controller”一律归为大小限制。

真正保存文件时，也别直接信任 getOriginalFilename() 作为磁盘路径；应重新生成安全文件名，并校验允许的类型与大小。允许 20MB 上传不等于允许任何人无限次上传。若是 JSON 参数问题而非文件 part，可再看Spring Boot 接收 JSON 参数；配置未生效则对照配置文件排查。

参考资料

Spring Boot 3.5：Multipart 配置属性
Spring Boot 3.5：处理文件上传
Nginx：client_max_body_size

更新记录

2026-10-28：创建文章，补充代理与应用两层限制、multipart 格式和临时目录排查。