当Nginx返回413 Request Entity Too Large时，问题通常不在后端应用，而在于Nginx对HTTP请求体大小的预检查。client_max_body_size这个指令决定了Nginx愿意接收的客户端请求体最大字节数，一旦Content-Length或实际传输数据超过设定值，Nginx会立即中止读取并返回413，根本不会把请求转发给PHP、Node、Java等后端服务。这个机制是为了保护服务器资源，但也经常成为大文件上传失败的原因。下面结合配置文件、作用域和反向代理场景说明如何正确调整。
一、默认限制与413错误的表现
Nginx在没有显式配置client_max_body_size时，默认只允许1MB的请求体。无论是普通表单提交、文件上传还是JSON接口，只要请求体超过这个大小，Nginx就会直接返回413状态码，响应页面通常只有简单的错误提示。很多情况下开发者会先检查后端框架、应用日志或PHP配置，却发现请求根本没有进入应用层，这正说明是Nginx提前拦截了。
可以用curl命令快速验证。假设当前服务器是ipipp.com，上传一个3MB的文件，命令如下：
curl -X POST http://ipipp.com/upload \ -F "file=@./test_3mb.bin" -v
返回信息中如果出现HTTP/1.1 413 Request Entity Too Large，并且后端接口没有产生任何访问日志，基本可以确认是client_max_body_size设置过小。需要注意的是，即使请求使用Transfer-Encoding: chunked分块传输，Nginx同样会累计接收到的实际字节数，超过限额后立即断开连接，并不是只有带Content-Length的请求才会被限制。
二、配置位置与继承覆盖关系
client_max_body_size可以配置在http块、server块和location块中，作用范围从全局到局部逐级收窄。Nginx的配置继承规则是：子级如果没有显式设置，就使用父级的配置；一旦子级出现该指令，就完全覆盖父级的值，而不是叠加。因此，如果只在http块里写了20m，某些location可能仍然继承20m，但如果某个location单独写了1m，上传接口只要命中这个location就会回到1m限制。
下面是一个常见配置示例，在http层设置一个稍大的默认值，再针对上传接口单独调高：
http {
client_max_body_size 20m;
server {
listen 80;
server_name ipipp.com;
location /upload {
client_max_body_size 100m;
}
location / {
# 其他请求继承http层的20m
}
}
}
修改完配置文件后，不要直接重启线上服务，先用nginx -t检查语法，再执行nginx -s reload平滑加载。单位方面，Nginx支持k、m、g等后缀，大小写不敏感，1m表示1MB，也就是1024KB。如果把值设为0，表示不限制请求体大小，但在公网环境不建议这样做，因为攻击者可能利用超大请求体消耗带宽和磁盘，更合理的做法是根据业务允许的最大文件尺寸设置一个明确上限。
三、反向代理场景与后端大小限制要协同
如果Nginx后面还代理了应用服务，client_max_body_size只决定Nginx接收客户端请求体的大小，并不会控制后端返回给Nginx的响应体大小，也不会自动让后端接受同样大小的上传。很多上传失败的问题是在Nginx放宽之后仍然出现，原因往往在后端语言或框架自身的上传限制。例如PHP需要同步调整php.ini中的upload_max_filesize和post_max_size，Java Spring Boot需要调整spring.servlet.multipart.max-file-size和max-request-size，Node.js的某些中间件也有独立的body大小约束。
因此在排查上传故障时，应当把链路拆开来看：客户端到Nginx这一段由client_max_body_size控制；Nginx到后端这一段由后端服务自身的上传配置控制。只有两段都满足上传需求，文件才能完整写入存储。可以通过在Nginx日志中确认是否出现413，再结合后端错误日志判断请求是否已经到达应用层。如果Nginx没有413，但后端返回400或500，就应该检查后端配置而不是继续调大Nginx的值。
四、常见配置误区与日志辅助定位
一个典型误区是修改了配置文件但没有重载Nginx，或者重载了错误的配置文件。线上环境可能同时存在多个Nginx实例或容器，本地修改的nginx.conf不一定就是实际生效的那份。可以用nginx -T命令查看当前生效的完整配置，并搜索client_max_body_size出现的层级，确认最终值是否符合预期。
另一个容易忽视的问题是location匹配。Nginx的location匹配规则比较复杂，前缀匹配、正则匹配、精确匹配的优先级不同。如果上传请求命中的是另一个location块，而该location中没有覆盖client_max_body_size，就可能使用了父级或更外层的值。排查时不要只看配置里写了什么，还要结合请求URI判断实际进入哪个location。必要时可以在server块统一设置一个安全上限，再只对特殊上传路径调整，减少匹配带来的不确定性。
Nginx错误日志也会留下关键线索。当请求体超限时，error_log中通常会出现类似client intended to send too large body的记录，配合日志时间可以快速定位到具体请求。同时，使用curl的-v参数能看到完整的响应头和状态码，这些信息比浏览器默认显示的友好错误页更有排查价值。理解了指令的作用域、继承关系以及整条请求链路的限制点之后，上传文件大小的调整就会清晰得多。
Nginxclient_max_body_size413错误修改时间：2026-10-02 14:23:54