spring boot 应用部署后大文件（>100mb）上传返回 503 错误，请求甚至未到达控制器——根本原因常是 multipart 功能未显式启用，而非仅配置大小限制。
在 Spring Boot 中，即使你已正确设置了 spring.servlet.multipart.max-request-size 和 spring.servlet.multipart.max-file-size 等参数，若未显式启用 multipart 支持，Tomcat（或其他嵌入式容器）将直接拒绝包含 multipart/form-data 的请求，导致 503 Service Unavailable 错误，且日志中无任何处理痕迹——这正是你观察到“本地正常、线上 503 且无日志”的关键原因。
✅ 正确配置：必须显式启用 multipart
Spring Boot 2.0+ 默认 spring.servlet.multipart.enabled=true，但 Spring Boot 1.x（如你使用的 5.0.8.RELEASE 对应的 Boot 版本通常为 2.0.4 之前）默认值为 false。因此，务必在 application.properties 中添加：
# 必须启用 multipart 支持（尤其 Spring Boot < 2.0.5） spring.servlet.multipart.enabled=true # 文件大小限制（单位可为 MB/GB，如 500MB） spring.servlet.multipart.max-request-size=500MB spring.servlet.multipart.max-file-size=500MB # Tomcat 额外限制（针对 form-data 解析缓冲区） server.tomcat.max-http-form-post-size=524288000 # 500MB，单位为字节
⚠️ 注意：server.tomcat.max-http-form-post-size 的单位是字节（非 MB），推荐使用精确数值（如 524288000 = 500 * 1024 * 1024），避免因单位解析歧义导致配置失效。
? 验证请求是否抵达服务端
- 若 enabled=false，请求会在容器层被拦截，Controller 完全不会执行，日志中也无 DispatcherServlet 入口记录；
- 启用后，可通过添加简单日志验证：
@PostMapping("load/largefile") public ResponseObj loadHeavyFileToS3(@RequestPart("file") MultipartFile jsonDataFile) { System.out.println("✅ Request received. File name: " + jsonDataFile.getOriginalFilename()); System.out.println("? File size: " + jsonDataFile.getSize() + " bytes"); return new ResponseObj(true, loadService.load(jsonDataFile)); }
? 部署环境额外注意事项
由于你明确指出“本地 OK，线上 503”，除应用配置外，请同步检查生产环境前置组件：
-
反向代理（Nginx / ALB / API Gateway）：它们通常有独立的请求体大小限制。例如：
- Nginx：需配置 client_max_body_size 500M;（在 http、server 或 location 块中）；
- AWS ALB：默认最大请求体为 1MB，需通过 Target Group 属性或升级为 NLB + 自定义负载均衡策略；
- Cloudflare：免费版限制 100MB，需企业版支持更大上传。
- 防火墙或 WAF 规则：可能主动拦截超大 POST 请求并返回 503。
✅ 推荐完整配置清单（application.properties）
# Multipart 核心开关（不可省略！） spring.servlet.multipart.enabled=true # 大小限制（建议统一设为略大于业务需求） spring.servlet.multipart.max-file-size=500MB spring.servlet.multipart.max-request-size=500MB # Tomcat 底层缓冲区（字节单位，必须 ≥ max-request-size） server.tomcat.max-http-form-post-size=524288000 # 可选：提升上传稳定性（防止超时） server.tomcat.connection-timeout=600000 # 10分钟
? 总结
503 错误在大文件上传场景中，往往不是业务逻辑问题，而是基础设施层的“准入拦截”。首要排查点永远是 spring.servlet.multipart.enabled=true 是否生效；其次才是大小阈值与网关限制。配置生效后，建议使用 curl 发送最小复现请求进行端到端验证：
curl -X POST http://your-server/load/largefile \ -F "file=@large-file.zip" \ -v
通过 -v 查看完整响应头，确认状态码及 Content-Length 是否被正常接收。
