解决Spring Boot上传默认限制文件大小和完善超限异常（若依框架）

文章目录

报错信息
问题分析
技术原理
解决方法
- [1️⃣调整 Spring Boot 配置文件](#1️⃣调整 Spring Boot 配置文件)
- [2️⃣检查内嵌 Tomcat 配置（可选）](#2️⃣检查内嵌 Tomcat 配置（可选）)
- [3️⃣ 代码自定义配置（覆盖配置文件）](#3️⃣ 代码自定义配置（覆盖配置文件）)
全局异常处理代码

报错信息

bash 复制代码

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 中修改以下参数。

java 复制代码

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

xml 复制代码

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

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

若上传文件极大（如超过 2GB），需额外调整 Tomcat 的请求体限制
java 复制代码
```
server.tomcat.max-swallow-size=2GB  
```
xml 复制代码
```
server:
  tomcat:
    max-swallow-size: 2GB 
```

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

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

java 复制代码

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

全局异常处理代码

推荐存放位置：

bash 复制代码

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

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	可动态调整（根据业务规则）
代码侵入性	直接处理框架异常	通过异常转换解耦业务与框架实现