Nginx 的 client_max_body_size 未配置导致大文件上传被拦截返回413错误，因其在请求到达后端前就限制了请求体大小，默认仅1MB；需在 location 块中精准设置该值并同步调整 proxy_read_timeout、proxy_send_timeout、client_body_buffer_size 等参数。
Vue 项目部署在 Nginx 上，调用后端 API 上传大文件时卡住或返回 413 错误，问题大概率出在 client_max_body_size 没配对——它不是前端或后端的锅，而是 Nginx 在请求刚进来时就拦下了超限的请求体。
为什么改这个值才能让上传通？
Nginx 默认只允许 1MB 的请求体（含文件、JSON、表单数据），超过就直接返回 413 Request Entity Too Large。这个拦截发生在请求到达后端服务之前，所以：
- 前端 axios 看似发出了请求，但实际没走到后端，控制台可能无报错或只显示网络失败
- 后端日志完全收不到这次请求，查不到痕迹
- 即使后端（如 Spring Boot）已放开 multipart.max-file-size，Nginx 这道关卡仍会先截断
配置位置必须精准，不能只写在 http 块里
该指令支持 http / server / location 三级配置，且遵循“越具体越优先”原则。推荐按接口路径单独设置，避免全局放宽带来的安全风险：
- ✅ 推荐：写在上传接口匹配的
location块内，例如location /api/upload { client_max_body_size 500m; proxy_pass http://backend; } - ⚠️ 慎用：写在
server块里——整个站点所有接口都继承该限制，可能无意中放开非上传类接口 - ❌ 避免：仅写在
http块——影响所有虚拟主机，运维风险高
配套参数不能漏，否则大文件照样失败
光调大 client_max_body_size 不够。大文件上传耗时长、数据量大，还需同步调整：
- proxy_read_timeout 和 proxy_send_timeout：建议设为 3600（1 小时），防止 Nginx 在转发过程中因超时中断连接
- client_body_buffer_size：建议设为 512k～1m。它决定多大以内数据走内存，超过才写临时磁盘；太小会频繁刷盘，太大浪费内存
-
client_body_temp_path：确认该路径（默认
/tmp）磁盘空间充足，且 Nginx 运行用户有读写权限，否则写临时文件失败直接报 500
单位和取值要注意这些细节
单位不区分大小写，100m、100M、0.1g 都合法。特殊值：
- 设为
0表示禁用检查，允许任意大小上传——生产环境慎用，需确保后端有校验兜底 - 理论最大值取决于 Nginx 编译架构：64 位环境下可达约 8 EiB（远超实际需求），不必担心上限
- 修改后必须重载配置：
sudo nginx -t && sudo nginx -s reload，仅重启服务不够
