必须在匹配上传路径的location块中设置client_max_body_size才生效，因Nginx优先级为location>server>http；若仅在http或server块配置而location未显式声明，则继承默认1M导致413错误。
client_max_body_size 必须写在 location 块里才生效
很多人改了 client_max_body_size 却还是 413，根本原因是它没出现在实际匹配的 location 块中。Nginx 配置优先级是 location > server > http，哪怕你在 http 块设了 500m，只要上传请求命中的是 /api/upload 这个路径，而该 location 块里没重写，就可能继承默认的 1m。
✅ 正确做法：在转发上传请求的 location 块内直接设置：
location /api/upload {
client_max_body_size 500m;
proxy_pass http://backend;
}
- 别只在
server块设——会放宽所有 POST 请求（比如登录接口），增加攻击面 - 别依赖继承——Nginx 不自动“向下传递”该指令，必须显式声明
- 如果用宝塔面板，在网站配置文件的
location ~ \.php(.*)?上方或同级location块里加，别塞进if或嵌套块里
单位写法错一个字母就会 nginx -t 失败
client_max_body_size 支持 k、m、g，但大小写不敏感；唯一硬性要求是：不能混用大写字母和单位缩写，比如 100MB、500Mb 都会报语法错误，Nginx 启动失败。
- ✅ 合法写法：
100m、2g、512k、0.5g - ❌ 非法写法：
100MB、500Mb、2G、100 M（空格也不行） -
0表示禁用检查，生产环境慎用——后端必须有严格校验，否则磁盘可能被恶意上传打满
只调 client_max_body_size 还是会 500/502/超时
client_max_body_size 只决定“让不让进”，真正影响大文件上传稳定性的还有三个配套参数，缺一不可，且必须和它写在同一个 location 块里：
-
client_body_buffer_size：建议设为512k～1m。太小（如默认8k）会导致频繁刷盘；太大浪费内存 -
client_body_temp_path：确认路径（如/var/tmp/nginx/body）磁盘空间够，且 Nginx 运行用户（如www-data）有读写权限，否则报open() failed (13: Permission denied) -
proxy_read_timeout和proxy_send_timeout：建议都设为3600（1 小时）。Nginx 要等整个请求体收完才转发，超时就直接断连，前端看到的是网络错误而非 413
这些参数不和 client_max_body_size 写在一起，就无法协同生效。
后端限制不调，Nginx 放行也没用
Nginx 放行只是第一步。如果后端是 PHP，post_max_size 和 upload_max_filesize 必须 ≥ Nginx 的 client_max_body_size，否则会返回 502 或静默失败；如果是 Node.js/Python，也要检查框架层的 body 解析限制（如 Express 的 limit 选项、Django 的 DATA_UPLOAD_MAX_MEMORY_SIZE）。
- PHP 示例（php.ini）：
post_max_size = 512M、upload_max_filesize = 512M（注意单位必须是大写M，和 Nginx 不同） - 数值建议比 Nginx 多留 10–20MB 余量，避免边界情况触发截断
- 改完 Nginx 要
nginx -t && nginx -s reload；改完 PHP 要systemctl reload php-fpm或重启服务
最容易被忽略的是 client_body_temp_path 权限和后端超时设置——它们不会报 413，但会让上传卡在中间，日志里只有模糊的 500 或连接重置。
