报错信息

org.springframework.web.multipart.MaxUploadSizeExceededException: 
Maximum upload size exceeded] with root cause
org.apache.tomcat.util.http.fileupload.impl.FileSizeLimitExceededException:
The field file exceeds its maximum permitted size of 1048576 bytes.
at org.apache.tomcat.util.http.fileupload.impl.FileItemStreamImpl$1.raiseError(FileItemStreamImpl.java:117)
at org.apache.tomcat.util.http.fileupload.util.LimitedInputStream.checkLimit(LimitedInputStream.java:76)
at org.apache.tomcat.util.http.fileupload.util.LimitedInputStream.read(LimitedInputStream.java:135)

问题分析

• 日志显示 FileSizeLimitExceededException，表明上传文件大小超过 Spring Boot 默认的 **1MB（1048576 字节）**限制。这是 Spring Boot 对文件上传的安全保护机制，需通过配置调整解决。

技术原理

• Spring Multipart 机制：通过 MultipartResolver 解析上传请求，默认依赖 Tomcat 的 commons-fileupload 组件。
• 异常链路：DispatcherServlet → MultipartResolver → Tomcat文件流限制触发异常。
• 优先级：代码配置 > 配置文件 > 框架默认值。

解决方法

1️⃣调整 Spring Boot 配置文件

• 在 application.properties 或 application.yml 中修改以下参数。

  # 单个文件大小上限（示例设置为 10MB）
  spring.servlet.multipart.max-file-size=10MB  
  # 整个请求（含多文件）大小上限（示例设置为 100MB）
  spring.servlet.multipart.max-request-size=100MB  
  

  spring:
    servlet:
      multipart:
        max-file-size: 10MB # 单个文件大小上限（示例设置为 10MB）
        max-request-size: 100MB # 整个请求（含多文件）大小上限（示例设置为 100MB）
  

2️⃣检查内嵌 Tomcat 配置（可选）

• 若上传文件极大（如超过 2GB），需额外调整 Tomcat 的请求体限制

  server.tomcat.max-swallow-size=2GB  
  

  server:
    tomcat:
      max-swallow-size: 2GB 
  

3️⃣ 代码自定义配置（覆盖配置文件）

• 若通过代码配置了 MultipartConfigElement，需在 Bean 中显式设置限制

  @Bean 
  public MultipartConfigElement multipartConfigElement() {
      MultipartConfigFactory factory = new MultipartConfigFactory();
      factory.setMaxFileSize(DataSize.ofMegabytes(10)); 
      factory.setMaxRequestSize(DataSize.ofMegabytes(100)); 
      return factory.createMultipartConfig(); 
  }
  

全局异常处理代码

• 推荐存放位置：

  src/main/java/com/share/common/core/exception/handler/FileUploadExceptionHandler.java  
  

import org.springframework.http.HttpStatus; 
import org.springframework.http.ResponseEntity; 
import org.springframework.web.bind.annotation.ControllerAdvice; 
import org.springframework.web.bind.annotation.ExceptionHandler; 
import org.springframework.web.multipart.MaxUploadSizeExceededException; 
import com.share.common.core.exception.file.FileUploadException; 
 
@ControllerAdvice 
public class FileUploadExceptionHandler {
 
    /**
     * 捕获 Spring 原生文件大小超限异常 
     * 将其转换为您的业务异常体系 
     */
    @ExceptionHandler(MaxUploadSizeExceededException.class) 
    public ResponseEntity<String> handleSpringSizeLimit(MaxUploadSizeExceededException ex) {
        // 将 Spring 异常包装为业务自定义异常（保留原始异常栈）
        FileUploadException customEx = new FileUploadException("文件大小超出系统限制", ex.getCause()); 
        return handleBusinessException(customEx);
    }
 
    /**
     * 统一处理业务层的文件上传异常 
     */
    @ExceptionHandler(FileUploadException.class) 
    public ResponseEntity<String> handleBusinessException(FileUploadException ex) {
        String userFriendlyMsg = "上传失败：" + ex.getMessage(); 
        // 可根据 ex.getCause()  类型细化不同错误提示 
        return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE) 
               .body(userFriendlyMsg);
    }
}

特性	原始 Spring 方案	适配后方案
异常类型	MaxUploadSizeExceededException	FileUploadException
错误消息来源	框架默认提示	自定义业务提示
异常链保留	仅 Spring 异常栈	嵌套原始异常（ex.getCause() ）
状态码控制	固定为 413	可动态调整（根据业务规则）
代码侵入性	直接处理框架异常	通过异常转换解耦业务与框架实现