Nginx文件上传大小限制 如何修改client_max_body_size

client_max_body_size 是 nginx 限制客户端请求体大小的指令，默认值为 1mb，上传超限文件会直接返回 413 错误；需在 http/server/location 块中显式配置，优先级 location > server > http，单位支持 k/m/g（大小写敏感），修改后须 nginx -t 验证并 reload 生效。

client_max_body_size 是什么，为什么上传大文件会失败 Nginx 默认限制请求体大小为 1MB，当用户通过 POST 或 PUT 上传超过该尺寸的文件时，Nginx 直接返回 413 Request Entity Too Large 错误，根本不会把请求转发给后端应用（比如 django、flask、Node.js）。这不是后端代码的问题，也不是浏览器限制，而是 Nginx 在入口就拦截了。

这个值必须显式配置，且只对当前作用域生效——它不继承，也不自动向下传递。

在哪里设置 client_max_body_size 才有效 client_max_body_size 可以出现在三个层级：http、server、location。优先级从高到低是 location > server > http。但实际使用中：

• 设在 http 块里会影响所有虚拟主机，适合统一策略，但不够灵活
• 设在 server 块里适用于整个域名，比如只允许某个站点传大文件
• 设在 location 块里最精准，例如仅对 /upload 路径放宽限制，其他路径保持默认
• 如果后端是反向代理（如 proxy_pass），必须确保该指令出现在包含 proxy_pass 的 location 块内，否则无效

常见错误：只改了 http 块，但实际请求匹配的是某个 location，而该 location 没有声明该指令，就会回退到默认值（1MB）。

修改后必须 reload，且注意单位写法 改完配置必须执行 nginx -t 验证语法，再用 nginx -s reload 生效。热重载不重启 worker 进程，但旧连接仍按旧配置处理，新连接才用新规则。

client_max_body_size 100M;

单位支持 k、M、G（大小写均可），但不能写成 100MB 或 100m（小写 m 会被识别为毫秒，导致解析失败）。数值不能带空格，也不能用科学计数法。

如果设为 0，表示禁用限制（不推荐生产环境使用）。

还要同步检查后端和中间件的限制 Nginx 放宽只是第一步。很多后端框架或中间件也有自己的上传限制，容易漏掉：

• PHP：upload_max_filesize 和 post_max_size（php.ini）
• Python Flask：request.max_content_length
• Node.js express：body-parser 的 limit 选项，或 multer 的 limits.fileSize
• Java spring Boot：spring.servlet.multipart.max-file-size 和 max-request-size
• Cloudflare 等 CDN：可能自带 100MB 限制，需单独调整

只要其中任意一环没放开，上传仍会失败，而且错误表现可能不同（比如 400、500 或超时），排查时容易误判。

Nginx 的 client_max_body_size 是第一道门，但它不是唯一一道门。改完记得逐层确认，尤其注意 location 块的覆盖关系和单位大小写的细节。