Spring Boot中如何处理MaxUploadSizeExceededException异常

问题本质 #

你遇到的核心问题是：MaxUploadSizeExceededException是在Spring MVC控制器处理请求之前就被抛出的——Multipart文件解析器会提前校验文件大小，导致你的uploadFile方法根本没机会执行，包括你自己写的大小判断逻辑。

另外，移除application.properties的配置后依然报错，是因为Tomcat本身有默认的上传大小限制（默认2MB），即使去掉Spring的配置，Tomcat的默认规则还是会拦截超大文件。

两种有效解决方法 #

方法一：延迟Multipart解析，让异常进入控制器捕获流程 #

通过配置Multipart解析器开启延迟解析，把文件大小校验延迟到控制器方法执行阶段，这样就能用全局异常处理器捕获并返回自定义响应。

1. 自定义MultipartResolver配置

@Configuration
public class MultipartConfig {
    @Bean
    public MultipartResolver multipartResolver() {
        CommonsMultipartResolver resolver = new CommonsMultipartResolver();
        resolver.setMaxUploadSize(10 * 1024 * 1024); // 保持原10MB限制
        resolver.setMaxUploadSizePerFile(10 * 1024 * 1024);
        resolver.setResolveLazily(true); // 关键：延迟解析，让异常进入控制器流程
        return resolver;
    }
}

2. 全局异常处理器捕获异常

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ResponseEntity<String> handleFileTooLarge(MaxUploadSizeExceededException e) {
        return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
                .body("文件大小超出限制，最大允许10MB");
    }
}

方法二：自定义全局错误控制器 #

如果不想修改Multipart解析器，可以直接通过自定义ErrorController捕获全局错误，包括上传大小异常。

@RestController
@RequestMapping("/error")
public class CustomErrorController implements ErrorController {

    @GetMapping
    public ResponseEntity<String> handleError(HttpServletRequest request) {
        Throwable exception = (Throwable) request.getAttribute(RequestDispatcher.ERROR_EXCEPTION);
        
        if (exception instanceof MaxUploadSizeExceededException) {
            return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
                    .body("文件大小超出限制，最大允许10MB");
        }

        Integer statusCode = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        return ResponseEntity.status(statusCode != null ? statusCode : HttpStatus.INTERNAL_SERVER_ERROR)
                .body("请求处理失败");
    }

    @Override
    public String getErrorPath() {
        return "/error";
    }
}

补充：取消所有上传大小限制（可选） #

如果需要彻底移除大小限制，在application.properties中配置：

spring.servlet.multipart.max-file-size=-1
spring.servlet.multipart.max-request-size=-1

配置后Spring会自动覆盖Tomcat的默认限制，此时你可以完全用控制器内的自定义大小判断逻辑处理文件。

内容的提问来源于stack exchange，提问作者LDropl