Linux服务器Nginx上传大小限制如何设置?配置后怎样验证生效?
Linux服务器上通过Nginx接收上传请求时,限制通常由 client_max_body_size 控制。它可以写在 http、server 或 location 配置块中,例如 client_max_body_size 100m;;修改后不能只保存文件,还必须执行配置检查、重新加载Nginx,并用超过和低于限制的实际请求验证结果。
配置“不生效”时,优先检查三个位置:请求实际命中的 server/location 是否与修改位置一致,是否存在更具体的 location 覆盖了继承值,以及上传请求是否还经过PHP、应用框架、CDN或网关的第二层限制。Nginx返回 413 Request Entity Too Large 通常说明请求体已被Nginx拦截;如果Nginx放行后应用仍报文件过大,则需要继续检查后端限制。
现状与条件:先确认请求经过哪一层
这类调整适合已经运行Nginx的网站或接口环境。操作前先确认以下信息,避免把配置改在未生效的文件中:
- 当前站点使用的是哪个域名和端口。
- Nginx是直接提供上传接口,还是反向代理到PHP-FPM、Node.js、Java、Go等后端。
- 上传路径是
/upload、/api/file,还是由前端路由统一转发。 - 前端是否经过CDN、负载均衡、WAF或其他入口网关。
- 当前Nginx主配置文件和站点配置文件的实际路径。
- 变更是否需要避开业务高峰,以及是否具备回滚条件。
可以先查看Nginx编译时的默认路径:
nginx -V 2>&1
输出中通常能看到类似以下参数:
--conf-path=/etc/nginx/nginx.conf
--prefix=/usr/share/nginx
不同发行版、面板或容器环境的路径可能不同,不要仅凭经验编辑 /etc/nginx/nginx.conf。如果服务由systemd管理,可以先确认服务状态:
sudo systemctl status nginx --no-pager
如果系统没有 systemctl,可以改用:
sudo service nginx status
记录当前配置与业务状态
修改前建议至少备份准备编辑的文件。若主配置通过 include 引入多个站点文件,应同时备份实际要修改的站点文件,而不是只备份主配置。
例如站点配置位于 /etc/nginx/conf.d/example.conf:
sudo cp -a /etc/nginx/conf.d/example.conf \
/etc/nginx/conf.d/example.conf.bak.$(date +%Y%m%d-%H%M%S)
如果确认需要修改主配置,也单独备份:
sudo cp -a /etc/nginx/nginx.conf \
/etc/nginx/nginx.conf.bak.$(date +%Y%m%d-%H%M%S)
备份的影响范围是配置文件本身,不会立即改变运行中的Nginx。真正改变服务行为的是后续的配置加载或重新加载。保留备份后,如果新配置无法通过检查,或者重新加载后出现异常,可以恢复到原文件再执行验证。
日常操作:设置Nginx上传大小限制
认识 client_max_body_size
Nginx使用 client_max_body_size 限制客户端请求体的最大大小,单位可以使用 k、m、g 等后缀。默认值通常是 1m,但实际运行配置仍应以当前环境的有效配置为准。
常见写法如下:
client_max_body_size 100m;
这个配置控制的是整个HTTP请求体大小,不只是文件本身。使用 multipart/form-data 上传时,请求体还包含表单字段和分隔信息,因此文件大小应略小于配置值。例如设置为 100m 时,不应把一个恰好100 MB的文件作为唯一验收样本。
需要特别注意,100m 表示约100 MB的配置量级,不能直接等同于100 MiB。文件管理工具可能使用二进制单位显示大小,上传工具和网关也可能按十进制单位计算。验收时最好准备明显低于和高于限制的文件,而不要只测试边界值。
按站点设置:适合单个域名
如果只有一个站点需要放宽上传限制,可以放在对应的 server 块中:
server {
listen 80;
server_name upload.example.com;
client_max_body_size 100m;
location / {
proxy_pass http://app_backend;
}
}
这种写法只影响命中该 server 的请求,不会让所有虚拟主机都允许上传100 MB。对于同一台服务器承载多个站点的情况,按站点配置通常比直接修改 http 全局配置更容易控制影响范围。
HTTPS站点也应确认实际修改的是监听443端口的 server 块,而不是只修改了一个未被使用的HTTP配置:
server {
listen 443 ssl;
server_name upload.example.com;
client_max_body_size 100m;
location /api/ {
proxy_pass http://app_backend;
}
}
如果HTTP请求会被301或302跳转到HTTPS,最终上传请求通常在HTTPS的 server 中处理。此时只调整监听80端口的配置,可能不会改变真正的上传行为。
只对上传接口放宽:适合控制影响面
如果只有文件接口需要较大的请求体,可以把指令放在具体的 location 中:
server {
listen 443 ssl;
server_name upload.example.com;
client_max_body_size 10m;
location / {
proxy_pass http://app_backend;
}
location /api/upload {
client_max_body_size 100m;
proxy_pass http://app_backend;
}
}
上例中,普通请求仍受 10m 限制,/api/upload 路径允许到 100m。这比在全局统一设置大值更适合生产环境,因为大请求会占用连接、带宽、磁盘临时空间和后端处理资源。
如果上传路径使用精确匹配,需要把真实路径写准确:
location = /upload {
client_max_body_size 100m;
proxy_pass http://app_backend;
}
如果使用前缀匹配:
location ^~ /upload/ {
client_max_body_size 100m;
proxy_pass http://app_backend;
}
不要只看配置文件中“出现了 /upload”,还要确认请求URL是否实际命中这个块。例如 /api/upload/file 不一定会命中 location = /upload,而可能由另一个更通用的 location / 处理。
处理Nginx配置块的继承关系
client_max_body_size可以放在http、server或location上下文中。下级配置块没有单独设置时,通常会继承上级值;下级一旦写了自己的值,就会以更具体的配置为准。
例如:
http {
client_max_body_size 20m;
server {
server_name example.com;
location / {
proxy_pass http://app_backend;
}
location /upload/ {
client_max_body_size 100m;
proxy_pass http://app_backend;
}
}
}
在这个示例中:
example.com下未单独设置的请求通常继承20m。/upload/下的请求使用100m。- 如果另一个正则或精确匹配的
location接管了请求,实际值还要以最终命中的配置为准。
以下配置容易造成“明明改了但不生效”:
server {
client_max_body_size 100m;
location / {
client_max_body_size 10m;
proxy_pass http://app_backend;
}
}
访问根路径下的上传接口时,命中的是 location /,所以实际限制是 10m,不是 server中的100m。
修改配置并重新加载
编辑实际生效的站点配置文件:
sudo vi /etc/nginx/conf.d/example.conf
或使用服务器已有的编辑工具。增加配置后先不要立即重启,先检查语法:
sudo nginx -t
成功时通常会看到类似结果:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
确认检查成功后再重新加载:
sudo systemctl reload nginx
重新加载通常不会像停止再启动那样直接中断现有连接,但新请求会使用新配置。若没有systemd:
sudo service nginx reload
如果配置检查失败,不要强行重启。先根据报错修正文件,或者恢复备份后再次检查:
sudo cp -a /etc/nginx/conf.d/example.conf.bak.YYYYMMDD-HHMMSS \
/etc/nginx/conf.d/example.conf
sudo nginx -t
sudo systemctl reload nginx
备份文件名中的时间应替换为实际文件名。恢复操作会影响该站点对应的Nginx配置,恢复前应确认备份确实来自本次变更之前。
结果检查:不能只看配置文件,要验证实际请求
查看Nginx当前加载的完整配置
配置文件中存在某个参数,不代表运行中的Nginx已经加载了它。建议使用 nginx -T 查看解析后的完整配置:
sudo nginx -T > /tmp/nginx-effective.conf
然后搜索参数和站点:
grep -n -C 3 "client_max_body_size" /tmp/nginx-effective.conf
grep -n -C 3 "server_name upload.example.com" /tmp/nginx-effective.conf
nginx -T会展开include文件,并输出当前Nginx解析到的配置内容。输出可能包含上游地址、证书路径或其他内部信息,不要直接粘贴到公开工单或论坛。临时文件也应按服务器安全要求处理:
sudo rm -f /tmp/nginx-effective.conf
如果 nginx -T中完全找不到刚加入的配置,常见原因包括:
- 编辑的文件没有被主配置
include。 - 编辑了另一套Nginx实例的配置。
- 容器内外使用的不是同一份文件。
- 面板或部署工具在重新生成配置。
- 配置修改后没有成功reload。
nginx -t检查时使用的二进制与运行服务不是同一个实例。
确认请求命中了哪个站点和路径
可以先查看访问日志格式和内容:
sudo tail -f /var/log/nginx/access.log
如果站点使用独立日志文件,也要查看对应的配置:
grep -R "access_log" /etc/nginx 2>/dev/null
使用真实域名发起请求时,注意Host头、协议和端口必须与生产请求一致:
curl -vk -o /dev/null -sS \
-w 'HTTP=%{http_code} size_upload=%{size_upload} time=%{time_total}\n' \
-H 'Host: upload.example.com' \
-F 'file=@/tmp/test-5m.bin' \
https://127.0.0.1/api/upload
如果证书域名不匹配,-k仅用于本机验证时跳过证书校验,不建议作为正常客户端配置。更稳妥的方式是直接使用真实域名:
curl -v -o /dev/null \
-w 'HTTP=%{http_code} size_upload=%{size_upload} time=%{time_total}\n' \
-F 'file=@/tmp/test-5m.bin' \
https://upload.example.com/api/upload
测试文件可以用随机数据生成。下面命令生成约5 MB和约20 MB的十进制大小文件:
dd if=/dev/zero of=/tmp/test-5m.bin bs=1M count=5 status=progress
dd if=/dev/zero of=/tmp/test-20m.bin bs=1M count=20 status=progress
dd中的1M通常按二进制块计算,测试文件大小约为5 MiB和20 MiB。文件实际大小可用以下命令确认:
ls -lh /tmp/test-5m.bin /tmp/test-20m.bin
stat -c '%n %s bytes' /tmp/test-5m.bin /tmp/test-20m.bin
测试时建议使用明显分开的样本,而不是只准备一个恰好接近限制的文件。例如配置为 10m 时,可以使用约5 MiB的通过样本和约20 MiB的超限样本。预期结果如下:
| 测试样本 | 预期Nginx行为 | 主要判断 |
|---|---|---|
| 明显小于限制 | 请求进入应用,返回业务成功或业务层校验结果 | Nginx未提前拦截 |
| 明显大于限制 | 通常返回413 | Nginx请求体限制已生效 |
| 接近限制 | 结果受单位、表单开销和其他网关影响 | 不作为唯一验收依据 |
通过返回状态和日志定位拦截层
如果超大请求返回 413,同时Nginx错误日志出现请求体过大的记录,通常可以判断Nginx层限制生效。查看错误日志:
sudo tail -n 100 /var/log/nginx/error.log
部分系统使用systemd日志:
sudo journalctl -u nginx -n 100 --no-pager
不同版本或日志格式下,具体错误文字可能不同。判断时应结合状态码、请求时间和访问日志,而不是只搜索某一句固定文本。
如果Nginx返回 413,但没有进入后端应用日志,说明请求大概率在Nginx或更前面的网关被拦截。如果Nginx访问日志显示请求已转发,而应用日志报“文件过大”,则Nginx可能已经放行,问题转移到后端配置。
异常处理:配置存在但仍然不生效
情况一:改了server,实际命中了另一个server
Nginx会根据监听地址、端口、TLS状态和Host头选择server。以下情况容易选错配置:
- 使用IP访问,而配置只写了域名。
- 测试域名与线上域名不同。
- HTTP请求被跳转到HTTPS。
- 同一个端口存在多个
server_name。 - 通过负载均衡访问,测试请求没有到达修改过的节点。
- 本机使用
127.0.0.1测试,但线上请求经过另一套入口。
检查所有站点声明:
sudo nginx -T 2>/dev/null | grep -nE 'listen|server_name|client_max_body_size'
检查DNS解析和目标地址:
getent hosts upload.example.com
测试负载均衡后的每个节点时,应确认节点标识、访问日志时间和请求ID,避免只验证到其中一个实例。
情况二:更具体的location覆盖了配置
执行以下命令查看所有相关路径:
sudo nginx -T 2>/dev/null | grep -n -C 5 -E 'location|client_max_body_size'
重点核对:
- 是否存在
location = /api/upload。 - 是否存在
/api/或/这样的前缀匹配。 - 是否存在正则匹配,例如
location ~ \.php$。 - 上传路径是否被内部跳转到另一个URI。
- 配置是否由多个文件重复声明。
如果上传接口在PHP路径中,例如 /upload.php,请求可能命中PHP专用的正则location,而不是你修改的通用前缀。此时应把限制放在实际处理该请求的location,或者在server层设置统一值,再检查是否有下级覆盖。
情况三:Nginx放行,但PHP仍拒绝
PHP环境至少要检查以下参数:
php --ini
php -i | grep -E 'upload_max_filesize|post_max_size|max_file_uploads'
常见配置示例:
upload_max_filesize = 50M
post_max_size = 60M
post_max_size限制整个POST请求体,因此通常应大于upload_max_filesize,为多个文件和表单字段留出空间。如果通过PHP-FPM运行,还要确认修改的是FPM使用的配置,而不是命令行PHP的配置。可从PHP-FPM服务状态、站点诊断页或FPM池配置确认实际加载文件。
调整PHP参数后,通常需要重载PHP-FPM。例如服务名可能是php8.2-fpm或php8.1-fpm,不能直接套用未经核验的版本号:
systemctl list-units --type=service | grep -E 'php.*fpm'
确认服务名后再执行:
sudo systemctl reload php8.2-fpm
如果修改的是PHP-FPM进程配置,影响范围是所有使用该FPM池的站点;共享主机环境应先确认是否会影响其他应用。
情况四:后端框架或应用自身还有限制
应用可能在Nginx和PHP之外再次限制上传大小,例如:
- Java应用服务器的multipart限制。
- Node.js框架的body parser限制。
- Go服务读取请求体时设置了最大字节数。
- 应用按用户、角色或接口类型限制文件大小。
- 对文件扩展名、MIME类型或总数量进行校验。
- 临时目录空间不足,导致大文件上传失败。
排查时按请求链路由外到内进行:

- 先确认DNS、CDN或网关是否接受请求。
- 再看Nginx是否返回413。
- 再看Nginx是否将请求转发给上游。
- 检查后端服务日志和应用配置。
- 最后检查磁盘空间、临时目录权限和应用业务规则。
查看磁盘空间:
df -h
df -i
如果Nginx或应用使用独立临时目录,还要检查该目录所在分区。大文件上传可能同时占用请求缓冲、临时文件和最终存储空间,不能只看最终文件大小。
情况五:前置CDN、WAF或负载均衡先拦截
如果浏览器访问的是CDN或网关域名,客户端请求可能尚未到达源站Nginx。此时源站的client_max_body_size设置正确,也不能突破前置服务的请求体限制。
判断方法包括:
- 对比源站直连和正式域名的返回状态。
- 查看CDN或网关请求日志。
- 检查返回响应头中的网关标识。
- 查看源站Nginx访问日志是否出现该请求。
- 在测试窗口临时使用专用测试域名或内网入口验证源站。
不要只根据浏览器提示“上传失败”判断Nginx问题。若源站完全没有对应访问记录,排查重点应放在DNS、CDN、WAF、负载均衡或网络入口。
情况六:修改后重新加载失败
如果执行nginx -t提示语法错误,常见原因包括:
- 指令拼写错误。
- 少了分号。
- 把指令写在不支持的上下文中。
location或server大括号不匹配。include文件路径错误。- 修改文件权限导致Nginx无法读取。
- 面板生成的配置与手工文件发生冲突。
先查看完整错误位置:
sudo nginx -t
再根据文件名和行号打开对应配置。不要通过直接删除大量配置来“快速通过检查”,因为这可能导致站点路由、证书或反向代理配置一并丢失。
如果重载后服务状态异常,先查看日志:
sudo systemctl status nginx --no-pager
sudo journalctl -u nginx -n 100 --no-pager
在确认备份文件和恢复范围后,可以恢复本次修改的配置,再执行:
sudo nginx -t
sudo systemctl reload nginx
必要恢复:何时撤销放大的上传限制
上传限制调大后,Nginx可能需要处理更大的请求体,后端也可能增加内存、临时磁盘和连接占用。以下情况不宜长期保留过大的全局值:
- 只有一个接口需要大文件,却在
http层设置了数百MB或更大。 - 应用没有流式处理,大文件会长时间占用工作进程。
- 上传接口没有鉴权、速率限制或文件数量限制。
- 临时目录空间不足。
- 业务只需要几十MB,却为了绕过一次测试错误设置了
1g。 - 前端网关和后端限制不一致,造成用户反复重试。
恢复时优先撤销新增的location级配置,或者把值改回原来的站点值。例如原来限制为10m:
server {
server_name upload.example.com;
client_max_body_size 10m;
location /api/upload {
proxy_pass http://app_backend;
}
}
如果要完全恢复备份,先确认备份时间,再覆盖当前文件:
sudo cp -a /etc/nginx/conf.d/example.conf.bak.YYYYMMDD-HHMMSS \
/etc/nginx/conf.d/example.conf
sudo nginx -t
sudo systemctl reload nginx
恢复后重新进行一次小文件和大文件测试,确认站点已经回到预期限制。若变更涉及PHP-FPM、应用配置或网关,也要分别恢复对应层,不要只恢复Nginx就结束验收。
针对Nginx承载的网站、业务后台和文件接口,A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器租用资源,覆盖SSD、NVMe与大容量存储方案,并配备不同带宽线路和多IP产品,可为上传业务、接口服务、数据库及文件归档提供相应的计算、网络与存储基础。
上线或验收检查清单
- [ ] 已确认实际处理上传请求的域名、端口和节点。
- [ ] 已确认修改文件确实被主配置
include。 - [ ] 已查看
nginx -T,核对有效的client_max_body_size。 - [ ] 已检查
server和location是否存在更具体的覆盖配置。 - [ ] 已区分HTTP入口、HTTPS入口以及重定向后的最终请求。
- [ ] 已执行
nginx -t并确认语法检查成功。 - [ ] 已执行reload,并确认Nginx服务状态正常。
- [ ] 已用明显小于限制的文件测试正常上传或进入应用。
- [ ] 已用明显大于限制的文件测试,确认返回413或出现明确的Nginx拦截记录。
- [ ] 已检查PHP、应用框架、后端服务和前置网关的第二层限制。
- [ ] 已检查临时目录、目标存储目录的空间和权限。
- [ ] 已记录本次修改文件、限制值、测试文件大小和返回结果。
- [ ] 已保留可用备份,必要时能够恢复并重新加载。
- [ ] 已确认大上传限制只作用于需要的站点或接口,没有无意扩大到全部业务。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6356.html



