必须在匹配上传路径的 location 块中设置 client_max_body_size，因为 nginx 配置继承顺序为 location > server > http，未显式配置的 location 会回退到默认 1mb 限制，导致 413 错误。
在 Nginx 中，必须在匹配上传路径的 location 块里设置 client_max_body_size，否则即使全局配置了，该路径仍可能沿用默认 1MB 限制，导致上传返回 413 错误。
为什么一定要写在 location 里？
Nginx 的配置继承顺序是：location > server > http。如果你的上传接口是 /api/upload 或 /upload/，而只在 http 或 server 块中设置了 client_max_body_size，但没在对应 location 中重写，Nginx 实际生效的仍是更精确匹配块里的值——而多数默认配置中，该 location 并未显式声明，就会回退到内置默认值（1M）。
- ✅ 正确示例（针对 API 上传路径）：
location /api/upload {<br> client_max_body_size 500m;<br> proxy_pass http://backend;<br>} - ✅ 正确示例（针对静态上传目录）：
location /upload/ {<br> client_max_body_size 2g;<br> # 其他如 root、autoindex 等配置<br>} - ❌ 错误做法：仅在
server块设了100m，但location /api/upload内没写，结果上传仍被拦在 1M
配套参数不能漏
client_max_body_size 只决定“允许多大”，不保证“传得稳”。大文件上传还依赖缓冲、临时文件和超时控制：
-
client_body_buffer_size：建议设为512k或1m。太小（如默认 8k）会导致频繁刷盘；太大浪费内存。若设为与client_max_body_size相同，可强制全程走内存（仅适合低并发场景） -
client_body_temp_path：确认路径（如/var/tmp/nginx/client_body）磁盘空间充足，且 Nginx 运行用户（如www-data）有读写权限，否则报Permission denied -
proxy_read_timeout和proxy_send_timeout：上传耗时长，建议设为3600（1 小时），避免连接提前中断
怎么验证配置生效？
改完配置别急着测业务接口，先加个简易测试 location：
- 在配置中加入：
location /test-size {<br> client_max_body_size 1g;<br> return 200 "OK, max body size = 1G";<br>} - 执行
sudo nginx -t && sudo nginx -s reload - 访问
http://your-domain/test-size，返回 200 表示语法正确、加载成功 - 再用真实上传请求（如 curl 或前端表单）测试目标路径，观察是否仍返回 413
常见误区提醒
不要把 client_max_body_size 误写成 HTTP 请求头（比如 Client-Max-Body-Size），它只是 Nginx 配置指令，不是客户端能发送的字段。也不要在 if 块或 map 中尝试动态设置——该指令不支持运行时条件判断，只接受静态值。
