必须在location块中显式配置client_max_body_size，因其优先级最高；还需同步调大client_body_buffer_size、确保client_body_temp_path权限正确、延长proxy_read_timeout等超时参数，并校准后端限制与请求头缓冲，否则仍会因缓冲、权限、超时或头部过大导致413/500/502/400错误。
client_max_body_size 是 Nginx 控制请求体大小的核心参数，直接决定文件上传能否通过第一道关卡。它不解决全部问题，但设错位置或漏配关联项，上传必然失败。
必须写在匹配路径的 location 块里
Nginx 配置遵循“location > server > http”的优先级规则。即使你在 server 块设了 `100M`，如果上传请求实际命中的是 `/api/upload` 这个路径，而该路径下没有显式配置，Nginx 就可能沿用默认的 `1M` 或其他继承值，导致 413 错误。- ✅ 推荐写法：在具体转发路径中设置
location /api/upload { client_max_body_size 500m; proxy_pass http://backend; } - ❌ 常见错误：只在 http 或 server 块设值，却没覆盖到实际上传路径
- ⚠️ 慎用：在 server 块统一设大值，会让所有 POST 请求（如登录、表单提交）都放宽限制，增加潜在风险
单位写法与数值建议
参数值支持 `k`、`m`、`g` 单位（大小写不敏感），不加单位默认为字节。- 常用写法：
100m、2g、512k -
0表示禁用检查（生产环境慎用，需后端有严格校验兜底） - 数值应略大于后端限制（如 PHP 的
post_max_size），建议多留 10–20MB 余量
配套参数缺一不可
`client_max_body_size` 只管“让不让进”，真正影响上传稳定性的还有三项：-
client_body_buffer_size：内存缓冲区大小，推荐512k～1m；太小会频繁刷盘，太大浪费内存 -
client_body_temp_path：临时文件路径，确保磁盘空间充足，且 Nginx 运行用户（如www-data）有读写权限 -
proxy_read_timeout和proxy_send_timeout：建议设为3600（1 小时），避免大文件传输中途超时断连
这些参数需和 client_max_body_size 写在同一作用域（例如同在 /api/upload 的 location 块内），否则无法协同生效。
后端限制必须同步放开
Nginx 放行后，请求才会到达后端。若后端仍有硬限制，会出现 502、500 或静默失败：- PHP（含 ThinkPHP）：调整
php.ini中upload_max_filesize = 500Mpost_max_size = 512M（必须 ≥ upload_max_filesize）memory_limit = 600M
修改后需重启 PHP-FPM，不是重载 Nginx - Spring Boot：在
application.yml中设spring: servlet: multipart: max-file-size: 500MB max-request-size: 500MB - Node.js（Express + Multer）：
app.use(upload.single('file'));需配合limits: { fileSize: 500 * 1024 * 1024 }
还要留意 CDN 或云负载均衡器（如阿里云 SLB、Cloudflare）是否设置了独立的请求体限制，它们的配置优先于 Nginx，需一并调大。
验证是否生效
- 执行 `nginx -t` 检查语法，再 `nginx -s reload` 重载配置 - 用 curl 测试边界值： `curl -F "file=@test.zip" http://your-domain.com/api/upload` - 查看 Nginx 错误日志：`tail -f /var/log/nginx/error.log` - 若出现 `413 Request Entity Too Large`，说明仍被拦截；若报 `500` 或连接中断，则大概率是缓冲、权限或超时问题不复杂但容易忽略
