Nginx 上传文件出现 413 怎么办？文件大小限制与反向代理排查教程

在网站后台上传图片、视频或压缩包时，小文件可以成功，大文件却提示 413 Request Entity Too Large，通常需要检查上传请求经过的各层大小限制。

有时已经修改了 Nginx 配置，上传依然失败。原因可能是改错了站点、被更具体的配置覆盖，或者请求在 CDN、后端应用处再次被拦截。

本文以 Linux 服务器上的 Nginx 为例，按“确认报错来源、修改正确配置、检查其他限制、重新上传验证”的顺序排查。在莱卡云服务器上部署网站、图床或自建应用时，也可以参考这个流程。

文中的域名、容器名、配置路径和接口地址均为示例，需要替换成实际信息。修改前先备份对应配置文件。

一、413 错误是什么意思？

413 表示请求内容超过了接收方允许的大小。常见提示包括：

413 Request Entity Too Large
413 Payload Too Large

这里限制的往往是整个请求体，不只是某一个文件。

例如使用表单上传时，请求体还包含表单字段和 multipart 边界；一次上传多个文件时，还需要计算它们合计占用的空间。

Nginx 的 client_max_body_size 默认值为 1m，实际部署可能已经被站点配置、容器模板或管理面板修改，不能直接假定当前服务器仍使用默认值。

另外，413 也可能由前面的 CDN、网关或后端应用返回。页面上出现 Nginx 字样，或者响应头包含 Server: nginx，都不足以单独确定是哪一层拒绝了请求。

二、先找到真正失败的上传请求

打开浏览器开发者工具，进入“网络”或“Network”面板，再上传一次测试文件。

重点记录：

哪一个请求返回了 413；
上传使用的域名和接口路径；
请求方法，例如 POST；
测试文件大小和发生时间。

网站页面和上传接口可能使用不同域名。只修改首页对应站点，未必会影响真正的上传接口。

随后查看处理该请求的 Nginx 错误日志。对于使用常见默认路径的安装，可以执行：

sudo tail -n 100 /var/log/nginx/error.log

如果出现类似关键词：

client intended to send too large body

并且时间、域名或接口与本次测试对应，说明这层 Nginx 检测到了请求体超限。

日志路径应以当前站点的 error_log 配置为准。没有找到这条日志，不能直接认定是 CDN 的问题，还要确认是否查看了正确实例和日志文件。

三、确认处理上传请求的 Nginx 配置

查看 Nginx 当前磁盘上的配置及其包含文件：

sudo nginx -T

重点核对上传域名对应的 server_name、监听端口、实际匹配的 location，以及其中的 client_max_body_size。

不要只搜索到一行 client_max_body_size 就结束检查，还要看它属于哪个站点和路径。

同一台服务器可能存在系统安装的 Nginx、面板安装的 Nginx，以及 Docker 中的 Nginx。检查命令必须对应正在处理上传请求的那个实例。

如果启动时使用了自定义 -c 配置文件或 -p 前缀，检查时也需要使用相同参数。

还要注意：nginx -T 展示的是当前磁盘配置，并不能证明正在运行的工作进程已经加载了刚修改的内容。

四、正确设置 client_max_body_size

检查 server 与 location 中的 client_max_body_size 上传限制

假设业务允许单个文件最大约 50MiB，可以先按单文件上传场景，为整个请求体预留一定余量，例如：

client_max_body_size 64m;

在处理上传请求的现有 server {} 中新增或修改这一行即可，保留原来的域名、证书、认证和转发配置。

该指令可以放在 http、server 或 location 中，不能随意写在主配置文件的最外层。

如果更具体的 location 单独设置了大小，就需要检查它的值。例如下面的片段用于说明配置关系：

server {
    server_name upload.example.com;
    client_max_body_size 64m;

    location /api/ {
        client_max_body_size 8m;
        proxy_pass http://127.0.0.1:8080;
    }
}

对于匹配这个 /api/ 的请求，仍然使用 8m 限制。只修改外层的 64m，不会覆盖这里明确设置的值。

应根据业务需要修改这个已有的 location，或者移除其中的单独设置，让它继承上层限制。不要为了加一条大小配置，另建一个同名 location，或删掉原有的认证和转发规则。

64m 只是本文的配置示例。如果一个请求同时上传多个文件，需要按整个请求体估算，不能只参考其中最大的单个文件。

在本地隔离测试中，发送同一个 9MiB 请求体，得到以下结果：

测试配置	测试结果
`server` 为 64m，匹配的 `location` 为 8m	返回 413
`server` 为 64m，`location` 未单独设置大小	测试后端收到完整请求体
将原 `location` 改为 64m，检查并重载后	原上传路径恢复接收完整请求体

这也是为什么“配置里已经出现 64m”，不代表上传接口实际使用的就是 64m。

五、检查配置并重新加载

修改完成后，先检查配置：

sudo nginx -t

只有检查通过后，才重新加载。对于确实由 nginx.service 管理的系统安装，可以执行：

sudo systemctl reload nginx

如果配置检查报错，应先处理具体错误，不要继续反复重载。

面板安装和容器安装应使用对应的管理方式，避免检查的是一个实例，重载的却是另一个实例。

重新加载后，再发起一次新的上传请求，结合日志确认结果。旧请求已经收到的 413 不会因为修改配置而自动变成成功。

六、PHP 网站还要检查应用侧上传限制

如果后端使用 PHP，Nginx 放行请求后，PHP 仍然可能拒绝或无法正常解析上传内容。

需要重点检查：

upload_max_filesize = 50M
post_max_size = 64M

upload_max_filesize 控制单个上传文件的最大值，post_max_size 控制 POST 数据总量。后者应大于前者，为表单等额外内容留出空间。

如果 POST 数据超过 post_max_size，PHP 的 $_POST 和 $_FILES 可能为空，网站不一定继续显示标准的 413 页面，也可能提示上传失败或没有收到文件。

修改时应确认网站实际使用的 PHP-FPM 版本及其配置。终端中 php --ini 显示的 CLI 配置，不一定就是网站使用的配置；FPM 池配置、站点配置也可能覆盖相关参数。

修改后，按实际部署方式重新加载对应的 PHP-FPM 服务，并从网站侧确认生效。仅重新加载 Nginx，不会让 PHP-FPM 自动重新读取它自己的配置。

WordPress 插件、网盘程序、接口框架等还可能设有独立的文件大小或类型限制，需要结合应用提示继续检查。

七、Docker 部署时，检查容器内的 Nginx

如果反向代理运行在 Docker 中，宿主机上的 /etc/nginx 可能与容器实际使用的配置无关。

假设容器名为 web-nginx，先查看它的配置：

docker exec web-nginx nginx -T

修改对应的配置来源后，在容器内检查并重新加载：

docker exec web-nginx nginx -t &&
docker exec web-nginx nginx -s reload

这些命令同样需要对应容器实际使用的程序和配置路径。若容器启动时使用了自定义参数，也应一并核对。

建议修改 Compose 挂载的配置文件或实际生成配置的模板，不要只临时编辑容器内部文件。否则容器重建后，这次修改可能丢失。

如果不清楚配置究竟保存在哪里，可以结合本站的《Docker 容器重建后数据不见了怎么办？》，检查挂载目录与数据持久化方式。

八、前面有 CDN 或多层反向代理怎么办？

网站使用 CDN、WAF、网关或多层 Nginx 时，每一层都可能设置独立限制。

例如源站已经允许 64m，但前面的代理只允许更小的请求体，那么请求仍然可能在到达源站之前被拒绝。

排查时可以对照以下证据：

观察结果	下一步检查
当前 Nginx 错误日志记录请求体超限	检查这一层的匹配配置
CDN 或网关日志明确记录大小限制	检查对应平台的上传上限和站点设置
源站收到请求，应用记录文件超限	检查后端框架或业务限制
源站没有相关请求记录	先确认日志已启用、路径和时间正确，再检查上游

使用 Cloudflare 等服务时，需要查看当前套餐及站点实际配置的上传上限，不能认为调大源站 Nginx 就能改变平台限制。

如果业务需要更大的文件，可以评估应用是否支持分片上传或对象存储直传。分片上传需要应用配合，不能仅靠添加一条 Nginx 配置实现。

九、修复后，用真实上传验证

普通打开首页，或者执行 curl -I，不能验证大文件上传限制是否已经修复，因为这类请求没有发送相同的上传内容。

应在测试账号和可清理的测试目录中，准备业务允许的文件格式，分别验证：

正常的小文件能够上传；
接近业务上限的文件能够上传；
超过业务上限的文件被合理拒绝；
上传后的文件可以正常读取或下载。

如果应用提供 multipart 表单上传接口，也可以参考下面的命令：

curl --max-time 120 -sS -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  -F 'file=@./upload-test.bin' \
  https://upload.example.com/api/upload

文件必须真实存在；字段名、文件格式、接口地址和认证方式应按应用要求调整。这个命令会实际上传文件，不要直接拿不明接口或生产业务数据测试。

HTTP 状态码只是一项检查结果。即使返回 200，也应确认应用没有在响应中报告错误，并检查文件确实保存成功。测试完成后清理测试文件。

十、几个常见误区

把 client_max_body_size 改成 0，可以解决所有上传问题吗？

不能。0 只关闭这一层 Nginx 的请求体大小检查，其他代理和应用的限制仍然存在。通常应按业务需要设置明确上限，同时考虑并发上传和临时文件占用。

调大 client_body_buffer_size，就能上传更大的文件吗？

不能。它控制读取请求体时使用的缓冲区大小，并不是请求体上限。不应为了修复 413，把缓冲区直接调到与最大文件一样大。

关闭 proxy_request_buffering 能绕过大小限制吗？

不能。它控制请求体是否先被缓冲再发送给上游，不会关闭 client_max_body_size 检查。proxy_buffering 则主要控制上游响应的缓冲，两者也不要混淆。

413 消失后，为什么又出现 502？

这时需要根据新的错误继续排查后端服务，而不是继续调大上传上限。可以参考本站的《Nginx 出现 502 Bad Gateway 怎么办？常见原因与排查教程》，检查上游连接和程序运行状态。

十一、结尾

Nginx 上传文件出现 413 时，先确认真正失败的请求和拒绝它的环节，再修改对应的请求体限制。尤其要核对上传域名、匹配的 location、容器配置和后端应用设置，避免只改到表面上的一处参数。

完成配置检查和重新加载后，再用接近业务上限的真实文件验证。把单文件大小、整个请求体大小以及各层限制分别确认清楚，才能让上传功能稳定工作，也方便以后调整和维护。