Nginx 中 proxy_body_size 限制反向代理上传大小-Nginx-PHP中文网

proxy_body_size 是 nginx 反向代理中限制客户端请求体原始字节大小的关键指令，仅作用于 nginx 转发给后端的请求体，需在 server 或 location 块中配置，与 client_max_body_size 配合使用以防上传失败。

nginx 中 proxy_body_size 限制反向代理上传大小

proxy_body_size 是 Nginx 反向代理中控制客户端请求体（request body）最大允许尺寸的关键指令，直接影响文件上传能否成功。它不作用于响应体，只管“客户端发给 Nginx”的那部分数据——比如表单提交的文件、JSON 请求体、大块 POST 数据等。

这个值到底限制什么

它限制的是整个 HTTP 请求体的原始字节大小，不是解压后、不是 Base64 解码后，而是客户端实际发送过来的原始 payload。例如：

用户通过网页上传一个 8MB 的 ZIP 文件 → 请求体就是该 ZIP 的二进制流，需 ≤ proxy_body_size 设置值
前端调用 API 提交一个含 5MB 图片 Base64 字符串的 JSON → 整个 JSON 文本长度（含 base64 字符）必须 ≤ 该值
即使后端服务本身支持 100MB 上传，只要 Nginx 拦在前面且 proxy_body_size 设为 1M，就会返回 413 Request Entity Too Large 错误

在哪里配置才生效

该指令必须放在能处理请求体的位置：通常是在 server 块 或更精确的 location 块 中。仅写在 http 块里是全局默认，但容易被子块覆盖；若只在 upstream 或 events 块中设置则无效。

常见正确写法示例：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

server {
    listen 80;
    server_name upload.example.com;
<pre class="brush:php;toolbar:false;"># 允许该域名下所有路径上传最多 100M
client_max_body_size 100m;  ← 注意：这是 client_max_body_size，不是 proxy_body_size！

location /api/upload/ {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_buffering off;

    # ✅ 正确：限制发往后端的请求体大小（即 Nginx 转发给 backend 的 body）
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
    proxy_max_temp_file_size 0;

    # ⚠️ 关键：proxy_body_size 控制的是「Nginx 接收并转发给后端」的 body 上限
    proxy_body_size 100m;
}

}

⚠️ 特别注意：proxy_body_size 不是 client_max_body_size。前者管“Nginx 发给后端的 body”，后者管“客户端发给 Nginx 的 body”。两者常需同步设置，否则中间环节就卡住。

为什么上传失败却不报错？

有些情况看似没报错，实则是静默截断或超时，可能原因包括：

proxy_body_size 设得太小，但错误页面被自定义 413 页面掩盖，没看到原始提示
后端服务也有自己的 body 大小限制（如 Spring Boot 的 spring.servlet.context-parameters.max-http-post-size），形成双重限制
Nginx 启用了 proxy_buffering，而缓冲区不足导致临时文件写入失败，此时需配合 proxy_max_temp_file_size 和磁盘空间检查
HTTPS 场景下 SSL 缓冲或 TLS 分段也可能干扰大 body 传输，建议同时确认 ssl_buffer_size 和 keepalive 设置

调试与验证方法

上传出问题时，可按顺序排查：

查看 Nginx error.log，搜索 “client intended to send too large body” 或 “413”
用 curl 模拟上传并加 -v 参数，观察响应状态码和 headers
临时在 location 中添加 log_format + access_log，记录 $request_length 和 $body_bytes_sent 辅助判断
确认后端是否真实收到完整 body（如打印日志或用 tcpdump 抓包比对）