Nginx 413 Request Entity Too Large 错误：client_max_body_size 配置与排查

快速答案

• 结论：Nginx 返回 413 错误是因为默认的 client_max_body_size 为 1MB，上传文件超过此限制时触发。
• 第一检查：确认 Nginx 配置中 client_max_body_size 的值是否小于上传文件大小，并检查后端服务（如 PHP-FPM、uWSGI）是否有独立限制。
• 最小修复命令：在 nginx.conf 的 http、server 或 location 块中添加 client_max_body_size 100m;，然后执行 nginx -s reload。
• 适用环境：适用于所有使用 Nginx 作为反向代理或 Web 服务器的场景，与操作系统、编程语言无关，但需注意后端服务的独立限制。

问题复现与根因分析

当用户通过浏览器或客户端向 Nginx 代理的服务器上传大文件（如视频、大型文档）时，Nginx 返回 HTTP 413 状态码，错误日志显示 client intended to send too large body。这是 Nginx 的默认安全限制——client_max_body_size 默认为 1MB，用于防止恶意客户端发送超大请求体耗尽服务器资源。

根因在于 Nginx 在接收完整请求体之前就会检查其大小，若超过限制则直接拒绝，不会转发给后端。因此，即使后端服务允许大文件上传，Nginx 也会拦截请求。

核心配置与参数说明

client_max_body_size 指令控制 Nginx 允许的请求体最大字节数。它可以在三个上下文中设置，作用域从宽到窄：

关键行为：

• 子上下文会继承父上下文的设置，但子上下文的显式设置会覆盖父上下文。
• 值可以设置为 0 表示不限制（不推荐生产环境使用）。
• 单位支持 k（千字节）、m（兆字节）、g（吉字节）。

配套参数（需同步调整）：

• client_body_buffer_size：请求体缓冲区大小，默认 8k 或 16k。超过此值则写入临时文件。
• proxy_request_buffering：是否缓冲请求体后再转发。设为 off 可实现流式上传，减少磁盘 I/O。
• proxy_read_timeout 和 proxy_send_timeout：后端响应和发送超时，大文件上传需适当增大（如 300s）。

与同类方案对比

亮点：Nginx 的 client_max_body_size 支持按 location 块精细化控制，且修改后无需重启进程，仅需 reload，对生产环境影响最小。

生产环境实践与注意事项

配置示例（可直接复制）

NGINX
http {
    # 全局默认限制
    client_max_body_size 10m;
    client_body_buffer_size 128k;

    server {
        listen 80;
        server_name example.com;

        # 普通 API 路径
        location /api/ {
            client_max_body_size 10m;
            proxy_pass http://backend;
        }

        # 大文件上传路径
        location /upload/ {
            client_max_body_size 200m;
            proxy_request_buffering off;  # 流式上传，避免磁盘缓冲
            proxy_pass http://upload-backend;
        }
    }
}

关键限制与安全建议

1. 内存与磁盘开销：增大 client_max_body_size 会增加 Nginx 的内存占用，因为请求体在转发前会缓冲到内存或磁盘。建议设置合理的 client_body_buffer_size（如 128k），超过部分写入临时文件。
2. SSL 场景：若启用 HTTPS，大文件上传可能导致 SSL 缓冲区溢出或超时，需同步调整 ssl_buffer_size。
3. 超时设置：设置 proxy_read_timeout 和 proxy_send_timeout 为较大值（如 300s），防止慢速攻击。
4. 速率限制：可配合 limit_rate 限制上传速率，防止单个连接占用过多带宽。
5. 权限控制：对上传路径进行认证和授权，防止未授权访问。
6. 请求头限制：client_max_body_size 仅限制请求体大小，不限制请求头。若请求头过大（如 Cookie），需调整 large_client_header_buffers。

后端服务同步调整

Nginx 限制解除后，后端服务可能仍有独立限制，常见场景：

• PHP-FPM：修改 php.ini 中的 upload_max_filesize 和 post_max_size。
• uWSGI：调整 buffer-size 参数。
• Gunicorn：调整 limit_request_line 参数。
• Node.js：检查 body-parser 中间件的 limit 选项。

常见报错与排查

错误 1：client intended to send too large body

原因：请求体超过 Nginx 的 client_max_body_size 限制。

解决步骤：

1. 在 nginx.conf 或站点配置的 http/server/location 块中增加 client_max_body_size 指令，例如 client_max_body_size 100m;。
2. 执行 nginx -t 检查配置语法。
3. 执行 nginx -s reload 使配置生效。

错误 2：client_max_body_size has no effect

原因：配置作用域错误或被其他块覆盖。

解决步骤：

1. 确认配置在正确的上下文（http/server/location）中。
2. 使用 nginx -T 查看完整配置，查找所有 client_max_body_size 出现的位置，确认没有冲突。
3. 检查 location 块是否匹配了请求的 URI（注意匹配优先级）。

错误 3：413 Request Entity Too Large（设置后仍出现）

原因：后端服务或中间件有独立限制。

解决步骤：

1. 检查后端服务配置（如 PHP-FPM 的 upload_max_filesize、uWSGI 的 buffer-size）。
2. 检查是否有 CDN 或负载均衡器（如 Cloudflare）的额外限制。
3. 检查请求头是否过大（如 Cookie），调整 large_client_header_buffers。

错误 4：upstream prematurely closed connection while reading upstream

原因：后端处理超时或缓冲区不足。

解决步骤：

1. 增大 proxy_read_timeout 和 proxy_send_timeout（如 300s）。
2. 确保 proxy_buffer_size 和 proxy_buffers 足够大。
3. 若上传大文件，考虑设置 proxy_request_buffering off 以禁用缓冲。

常见问题 FAQ

Q: 设置 client_max_body_size 后，为什么上传大文件时 Nginx 仍然返回 413 错误？

A: 可能原因：1) 配置未生效，需执行 nginx -s reload。2) 配置作用域错误，例如在 http 块设置但在 server 块被覆盖。3) 后端服务（如 PHP-FPM、uWSGI）也有自己的限制，需同步调整。4) 使用了 CDN 或负载均衡器，它们可能有独立限制。5) 请求头过大（如 Cookie），需调整 large_client_header_buffers。

Q: 增大 client_max_body_size 会影响服务器性能吗？

A: 会。Nginx 默认将请求体缓冲到内存（client_body_buffer_size），若请求体超过该值则写入临时文件。增大限制会增加内存和磁盘 I/O 开销。建议：1) 设置合理的 client_body_buffer_size（如 128k）以减少磁盘写入。2) 对于大文件上传，考虑使用 proxy_request_buffering off 实现流式转发。3) 监控磁盘使用和内存占用，避免 DoS 攻击。

Q: 如何为不同的 URL 路径设置不同的上传大小限制？

A: 在 server 块内使用多个 location 块分别设置。例如：

NGINX
location /upload/ {
    client_max_body_size 200m;
}
location /api/ {
    client_max_body_size 10m;
}

注意 location 匹配优先级（精确匹配 > 前缀匹配 > 正则匹配），确保规则按预期生效。使用 nginx -T 验证配置。