如何通过调整Nginx配置client_max_body_size突破大文件上传限制？

本文共计680个文字，预计阅读时间需要3分钟。

遇到413 Request Entity Too Large错误，基本原因是`client_max_body_size`这个值设置得太小了。它控制Nginx接收请求体的最大字节数（例如文件上传）。默认值通常是1MB，如果需要上传更大的文件，就需要调整这个值。

这个参数在哪设？三处位置区别明显

你可以在 Nginx 配置的三个层级中设置 client_max_body_size，作用范围不同：

• http { } 块里：全局生效，影响所有 server 和 location
• server { } 块里：只对该虚拟主机（域名或 IP 对应的服务）有效
• location { } 块里：仅对匹配该路径的请求起作用（例如 location /upload/）

推荐优先在 server 块里设——既避免影响其他服务，又比 location 更简洁可控。

怎么写？单位和特殊值要记牢

语法很简单：client_max_body_size 100M; 或 client_max_body_size 2G;。支持单位包括 k、m、g（大小写不敏感），不加单位默认是字节。

注意一个实用技巧：设为 0 表示不限制大小（慎用，仅限可信内网或调试环境）。

改完不生效？检查这几个关键点

配置保存后必须重载 Nginx 才会生效，但光重启还不够，常见遗漏项：

• 确认修改的是正在使用的配置文件（常为 /etc/nginx/nginx.conf 或 /etc/nginx/conf.d/*.conf）
• 运行 sudo nginx -t 检查语法是否正确，再执行 sudo systemctl reload nginx
• 如果用了反向代理（如把请求转给 Spring Boot 或 PHP），后端服务自身也有上传限制，必须同步调整（比如 Spring Boot 的 spring.servlet.multipart.max-request-size，PHP 的 upload_max_filesize 和 post_max_size）
• 临时目录权限问题：当上传体超过 client_body_buffer_size（默认 8KB–16KB）时，Nginx 会写临时文件到 client_body_temp_path（默认 /tmp）。确保运行 Nginx 的用户（如 www-data）对该路径有读写权限

附：一行快速验证是否生效

改完配置并重载后，可以临时加个测试 location：

location /test-upload {
  client_max_body_size 500M;
  return 200 "Max body size set to 500M";
}

访问该路径返回成功，说明语法和加载都没问题。再配合前端上传测试即可确认实际效果。