文件上传超限报错本质是服务端或中间件对 multipart/form-data 请求体设了尺寸限制，需从客户端提示、服务端配置、代码校验三方面协同解决，涵盖 Nginx、PHP、Spring Boot、Express 等多层配置及网关、云负载均衡等隐藏限制点，并统一返回 413 状态码与结构化错误信息。
文件上传大小超限报错，本质是服务端或中间件对请求体（尤其是 multipart/form-data）设了最大尺寸限制，超出即拒绝并返回 400 或 500 类错误。解决需从客户端提示、服务端配置、代码层校验三方面入手，不能只改一处。
后端框架配置调大上传限制
不同框架默认限制差异大，常见如 Spring Boot、Node.js（Express + multer）、PHP（php.ini）、Nginx 等，需逐层检查：
-
Spring Boot（内置 Tomcat）：在 application.yml 中添加
spring.servlet.multipart.max-file-size: 50MB<br>spring.servlet.multipart.max-request-size: 50MB
（注意：Spring Boot 2.0+ 已弃用multipart.前缀，改用spring.servlet.multipart.） -
Express + Multer：初始化 multer 实例时指定 limits：
const upload = multer({ limits: { fileSize: 50 * 1024 * 1024 } }); -
PHP（Apache/Nginx + PHP-FPM）：同步修改 php.ini：
upload_max_filesize = 50M<br>post_max_size = 50M
改完需重启 PHP-FPM 和 Web 服务器。 -
Nginx 层限制：在 server 或 location 块中加：
client_max_body_size 50M;
否则请求根本到不了后端应用。
代码中主动校验并友好提示
配置只是兜底，用户仍可能传超大文件。应在接收前做轻量校验，避免无效上传耗资源：
- Java（Spring MVC）中可在 Controller 方法参数前加 @RequestParam MultipartFile file，再手动判断：
if (file.getSize() > 50 * 1024 * 1024) {<br> throw new IllegalArgumentException("文件不能超过 50MB");<br>} - Node.js（Multer）可自定义 storage 或使用 fileFilter 拦截：
fileFilter: (req, file, cb) => {<br> if (file.size > 50 * 1024 * 1024) {<br> return cb(new Error('文件大小不能超过 50MB'));<br> }<br> cb(null, true);<br>} - 前端提交前也可用 JS 读取
input.files[0].size做前置提示，但不可替代后端校验。
排查链路中的隐藏限制点
上传失败不一定是你的应用代码问题，可能是中间某一层默默拦截：
- 云服务（如阿里云 SLB、腾讯云 CLB）有默认 10MB 的 POST 请求体限制，需在控制台调整；
- Docker 容器内运行的 Nginx 或 Java 应用，配置文件可能被镜像覆盖，确认挂载的是正确配置；
- Spring Cloud Gateway 等网关组件自身也有
spring.cloud.gateway.httpclient.max-in-memory-size参数，默认仅 2MB，需显式调大； - Tomcat 单独部署时，还需检查 server.xml 中 Connector 的
maxPostSize（单位为字节，-1 表示无限制）。
日志与错误码统一处理
上传超限应返回明确状态码和结构化错误信息，方便前端识别和提示：
- HTTP 状态码建议用 413 Payload Too Large（比 400 更语义准确）；
- 响应体统一 JSON 格式，例如：
{ "code": 413, "message": "文件大小超出限制（最大 50MB）", "field": "avatar" } - 在全局异常处理器（如 @ControllerAdvice）中捕获
MaxUploadSizeExceededException或 multer 的FileTooLargeError，转换为标准响应。
