Spring Boot 文件上传超限异常（MaxUploadSizeExceededException）默认不进入Controller层，而是在请求解析阶段被拦截；需在application.yml中同时配置spring.servlet.multipart.max-file-size和max-request-size（单位MB），并配合网关/Nginx校验及业务层精准检查。
Spring Boot 中文件上传超限异常（MaxUploadSizeExceededException）默认不会进入 Controller 层，而是在请求解析阶段（StandardMultipartHttpServletRequest.parseRequest）就被 Tomcat 或 Spring 的 multipart 解析器拦截并抛出。这意味着：即使你写了 @ControllerAdvice 全局异常处理器，也可能捕获不到——因为异常根本没走到 DispatcherServlet 的异常处理流程中。
关键配置必须前置生效
上传大小限制由两个核心参数控制，必须在 application.yml 或 properties 中明确设置，否则沿用 Spring Boot 2.x+ 默认的 1MB 限制：
-
spring.servlet.multipart.max-file-size：单个文件最大允许大小（如
20MB） -
spring.servlet.multipart.max-request-size：整个 multipart 请求总大小（含所有文件 + 表单字段，如
100MB）
⚠️ 注意：这两个值必须同时设置，且单位写法要规范（MB，不是 Mb 或 mb）。若只改一个，另一个仍为默认 1MB，上传仍会失败。
异常捕获要绕过“解析早于 Controller”的问题
由于异常发生在 Filter → Multipart 解析阶段，早于 @ControllerAdvice 生效时机，推荐两种可靠方式：
Java 接口排错助手
下载
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
- 启用 servlet 容器级兜底响应：确保配置后，Tomcat 会在超限时直接返回标准 HTTP 413（Payload Too Large），前端可据此统一提示
-
手动触发解析 + try-catch 包裹：在 Controller 方法中显式调用
request.getParts()或使用@RequestPart并配合 try-catch 捕获MaxUploadSizeExceededException，但需注意这会绕过自动绑定，适用性有限
生产环境建议双层校验
仅靠配置不够稳健，推荐组合策略：
-
yml 配置设宽松上限（如
max-file-size: 50MB），作为最后防线 -
业务代码内做精准校验：收到
MultipartFile后，先检查file.getSize()是否超过业务要求（如头像 ≤ 5MB），再抛出自定义异常（可被 @ControllerAdvice 捕获） -
网关或 Nginx 层同步配置：如使用 Nginx，需设置
client_max_body_size 50M;，否则请求在到达 Spring Boot 前就被拦截，连日志都看不到
避免常见陷阱
以下情况会导致配置看似生效、实则无效：
- 项目用了 Shiro、Spring Security 等安全框架，其过滤器链可能提前终止请求或吞掉异常
- 使用了自定义
MultipartResolver但未正确覆盖默认 Bean - Spring Boot 版本混淆：1.5.x 用
spring.http.multipart.*，2.0+ 必须用spring.servlet.multipart.* - IDE 运行时未加载最新配置（尤其多 profile 场景），建议启动日志中搜索
max-file-size确认是否被读取
