Spring Boot 文件上传大小限制问题：413 与 MaxUploadSizeExceededException 解决方案

📌 问题场景

在实际项目开发中，文件上传功能是一个常见的需求。最近在系统正式环境，遇到了两个典型的错误：

错误1：Nginx 层错误

复制代码

413 Request Entity Too Large
nginx/1.29.0

错误2：Spring Boot 应用层错误

复制代码

org.springframework.web.multipart.MaxUploadSizeExceededException: 
Maximum upload size exceeded; nested exception is java.lang.IllegalStateException: 
The field fileList exceeds its maximum permitted size of 1048576 bytes.

🔍 问题分析

这两个错误分别发生在不同的层次：

1. Nginx 默认限制

默认值：1MB（1048576 bytes）
作用位置：作为反向代理服务器，在请求到达应用前进行限制
错误表现：直接返回 413 状态码

2. Spring Boot 默认限制

默认值：同样为 1MB
作用位置 ：应用层，处理 MultipartFile 时进行校验
错误表现 ：抛出 MaxUploadSizeExceededException 异常

🛠️ 解决方案

方案一：Spring Boot 应用配置（主要方案）

方法1：通过配置文件设置（推荐）

application.yml 格式：

yaml 复制代码

spring:
  servlet:
    multipart:
      enabled: true
      max-file-size: 100MB        # 单个文件最大大小
      max-request-size: 100MB     # 整个请求最大大小

application.properties 格式：

properties 复制代码

spring.servlet.multipart.max-file-size=100MB
spring.servlet.multipart.max-request-size=100MB
spring.servlet.multipart.location=/tmp

方案二：Nginx 配置（如果使用 Nginx 作为反向代理）

nginx 复制代码

# 在 nginx.conf 或虚拟主机配置中
http {
    # 设置客户端最大请求体大小
    client_max_body_size 100M;
}

# 或在 server 块中配置
server {
    listen 80;
    server_name example.com;
    
    client_max_body_size 100M;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

📝 配置最佳实践

1. 微服务架构下的配置策略

复制代码

客户端 → Nginx → [Gateway] → 业务服务

组件	配置位置	配置项	建议值
Nginx	nginx.conf	`client_max_body_size`	应 ≥ 业务服务限制
Gateway	一般不需要	-	建议文件上传不走 Gateway
业务服务	application.yml	`spring.servlet.multipart.max-file-size`	根据业务需求设置

2. 配置值的一致性

yaml 复制代码

# 推荐：保持各层级配置一致
Nginx: client_max_body_size 100M;
Spring Boot: max-file-size: 100MB

# 关系：Nginx ≥ Spring Boot
# 错误示例：Nginx 50M，Spring Boot 100MB ❌

全局异常处理

java 复制代码

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.multipart.MaxUploadSizeExceededException;

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    @ResponseBody
    public String handleMaxUploadSizeExceededException(MaxUploadSizeExceededException e) {
        return "文件大小超过限制，请上传小于100MB的文件";
    }
}

📊 常见问题排查表

问题现象	可能原因	解决方案
413 错误	Nginx 限制太小	增大 `client_max_body_size`
MaxUploadSizeExceededException	Spring Boot 限制太小	增大 `max-file-size`
上传慢/超时	网络或服务器配置问题	调整超时时间，优化网络

希望这篇记录能帮助遇到类似问题的开发者！🚀