Nginx 413 Request Entity Too Large 请求体太大

FreeGuideOnline 最新 2026-07-05

什么是 Nginx 413 Request Entity Too Large 错误？

当你通过 Web 表单上传文件或提交大量数据时，浏览器可能会返回 413 Request Entity Too Large 错误页面。这表示你发送的请求体（也就是上传的数据）超过了 Nginx 服务器允许的最大尺寸，服务器拒绝处理该请求。

对于刚接触服务器配置的开发者来说，这个错误常常让人困惑，但它实际上只是一个需要调整的配置项。

错误产生的原因

Nginx 默认会限制客户端请求体的大小，以防止恶意或意外的大请求耗尽服务器资源。这个限制由指令 client_max_body_size 控制，默认值为 1MB。

当请求头中的 Content-Length 数值超过这个值时，Nginx 会立即返回 413 状态码，而不会将请求转发给后端的应用（如 PHP-FPM、Node.js 等）。

简单来说：

你上传了一个 2MB 的图片，而 Nginx 只允许 1MB → 413 错误
你通过 API 提交了一串很长的 JSON 数据，总体积超过 1MB → 413 错误

如何定位和确认问题

首先确认问题确实来自 Nginx，而不是后端应用。打开浏览器的开发者工具（F12），查看 Network 标签下失败请求的 Response Headers。通常会看到 Server: nginx 以及状态码 413。如果是来自 Nginx，响应内容通常是一段简短的 HTML。

下一步是检查 Nginx 当前配置中 client_max_body_size 的值。

查看当前设置

连接到服务器，使用下面的命令查看所有包含该指令的配置文件：

grep -r "client_max_body_size" /etc/nginx/

如果没有输出，说明你还没有显式设置过该值，那么所有上下文均使用默认的 1MB。

解决方案：修改 client_max_body_size

该指令可以在 http、server 或 location 块中使用，优先级由低到高。通常我们会在 server 块或特定的 location 块中修改它，以便精确控制。

通用场景：全局或站点级别增加限制

编辑你的站点配置文件（通常位于 /etc/nginx/sites-available/your_site 或 /etc/nginx/conf.d/your_site.conf），在 server 块中添加或修改：

server {
    listen 80;
    server_name example.com;

    # 将请求体限制提升到 50MB
    client_max_body_size 50M;

    # 其他配置...
}

单位说明：可以使用 K（千字节）、M（兆字节）、G（千兆字节），例如 10M、512K。如果设置为 0，则表示不检查请求体大小（不推荐，会让服务器面临风险）。

仅对上传接口增加限制

如果你只有一个特定的上传接口需要更大容量，可以在 location 块中定向设置：

location /upload {
    client_max_body_size 100M;
    # 可能还需要转发给后端，例如 proxy_pass 或 fastcgi_pass
}

这样，只有 /upload 路径下的请求可以接受 100MB 的上传，网站其他部分仍使用默认 1MB 或 server 块中更小的值。

反向代理场景

如果你的 Nginx 作为反向代理，且 413 错误是在代理返回的，处理方式相同。只需要在对应的 server 或 location 中设置 client_max_body_size。此外，如果后端服务也有自己的请求体大小限制，也需要一并调整（例如 PHP 的 upload_max_filesize）。

应用配置并验证

修改配置文件后，务必先测试配置语法是否正确，然后重新加载 Nginx：

sudo nginx -t

看到 syntax is ok 和 test is successful 后，执行：

sudo systemctl reload nginx
# 或较老系统使用 sudo service nginx reload

现在重新上传你的文件，413 错误应该消失。如果问题依旧，可以尝试以下排查步骤：

清除浏览器缓存，或使用无痕模式测试，排除浏览器缓存干扰。
检查 nginx.conf 主配置文件中是否在 http 块设了很小的值，而你的 site 配置没有覆盖它。
查看 Nginx 错误日志（通常为 /var/log/nginx/error.log），确认配置是否正确加载。
如果使用了 CDN 或前端负载均衡，确保这些环节也没有对请求体进行限制。

安全考量与相关优化

不要单纯因为避免 413 错误就将限制设置为一个极大的值。应遵循最小够用原则：

评估真实需求：你的用户通常会传多大的文件？文件上传 + 表单其他字段，总请求体会是多少？留出适当余量即可。
防范资源耗尽：过大的请求体会占用大量内存和带宽，可能导致拒绝服务。可以配合 client_body_buffer_size（内存缓冲区大小）和 client_body_timeout（读取请求体的超时时间）来进一步控制风险。
分层限制：在网络边界（如 WAF）、Nginx、应用层分别设置合理的限制，层层过滤。

以下是一个更完善的示例，同时设置了缓冲区与超时：

location /upload {
    client_max_body_size 20M;
    client_body_buffer_size 128K;      # 小于最大值时可灵活调整
    client_body_timeout 60s;           # 读取请求体超时时间
}

这样既满足了上传需求，又降低了大体积文件长期占用连接的风险。

常见连带问题：后端限制

即使 Nginx 的 413 问题解决了，你可能还会遇到其他限制，尤其是 PHP 环境：

PHP 配置：upload_max_filesize 和 post_max_size（后者需大于前者，且通常应等于或大于 Nginx 的 client_max_body_size）。修改 php.ini 后需重启 PHP-FPM。
应用层限制：某些框架或 CMS（如 WordPress）有自己的最大上传文件设置，需在后台调整。
超时设置：大文件上传耗时更长，Nginx 的 proxy_read_timeout 或 fastcgi_read_timeout 可能需要相应延长。

确保整个链路的大小限制一致，否则会在不同的环节收到不同的错误提示。

总结

413 错误的本质：请求体超过 Nginx 的 client_max_body_size 限制。
修复方法：在合适的 Nginx 配置上下文中（server 或 location）增加该值。
命令示例：client_max_body_size 64M;
验证与重载：nginx -t && systemctl reload nginx
安全原则：按需设置，避免无限制或过大值，并配合超时与缓冲区参数。

掌握这个配置项后，你就能从容应对各种文件上传和 API 大数据提交的需求。如果问题依然存在，请顺着请求链路逐层排查限制，确保前后一致。