---
title: NGINX 上传文件大小限制配置指南
description: 介绍通过 client_max_body_size 控制 NGINX 上传体积的方法，覆盖 http、server、location 三个作用域，并说明配置前的备份与测试要求、生效验证方式、回退步骤及常见问题，帮助运维人员在防范大体积请求类拒绝服务风险的同时避免误伤正常业务。
url: "https://www.lanever.com/docs/nginx-%e4%b8%8a%e4%bc%a0%e6%96%87%e4%bb%b6%e5%a4%a7%e5%b0%8f%e9%99%90%e5%88%b6%e9%85%8d%e7%bd%ae%e6%8c%87%e5%8d%97/"
updated: "2026-10-12"
category: Linux
---

# NGINX 上传文件大小限制配置指南

> **参考来源与致谢**
>
>
>
> - **引用来源：**[Limit File Upload Size in NGINX](https://docs.rackspace.com/docs/limit-file-upload-size-in-nginx)
> - **原作者：**原页面署名作者或发布机构（剪藏记录未保存可核验的个人署名）
> - **感谢词：**感谢原作者及发布机构对技术知识的公开分享。本文已结合企业运维场景完成脱敏、核验与原创重写，并非原文转载；如权利人需要更正署名或来源信息，请联系本站。

## 适用场景

NGINX 默认对单个请求体大小设有限制，超出限制的请求会被拒绝并返回 413 状态码。当业务需要支持较大的文件上传（如附件、镜像、备份包、日志归档）时，需要显式调整该阈值。合理设置上传上限可以降低大体积请求耗尽连接与带宽资源的风险，属于常见的拒绝服务防护手段之一。

本文适用于以 NGINX 作为反向代理或静态资源服务器的企业环境，涉及配置项为 `client_max_body_size`。不同版本对默认值、指令可用上下文及错误码表现可能存在差异，具体请查阅所用版本的官方文档。

## 准备与风险

- 确认 NGINX 配置文件路径，常见为 `/etc/nginx/nginx.conf`，站点配置可能位于 `/etc/nginx/conf.d/` 或 `/etc/nginx/sites-enabled/`。
- 确认当前生效的默认限制，可通过响应头或错误日志中的 413 记录判断。
- 确认上游应用（如应用服务器、对象存储网关）自身是否也有请求体大小限制，避免只改 NGINX 而请求仍被后端拒绝。
- 确认反向代理链路中是否存在其他中间层，例如负载均衡、WAF、CDN，它们可能各自设有独立上限。

> 修改前必须备份配置文件，并在测试环境验证后再应用到生产。放大的上限会同时放大资源消耗，请结合磁盘、内存、超时设置一并评估。

## 处理步骤

### 1. 备份配置

```
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%Y%m%d%H%M%S)
```

若使用独立站点配置文件，同样对其做备份。

### 2. 选择作用域

- `http` 块：影响所有 server 块，即全部虚拟主机。
- `server` 块：仅影响该站点或应用。
- `location` 块：仅影响该站点下某个上传目录。

作用域越精确，影响面越小。生产环境建议优先使用 `server` 或 `location`，避免全局放宽。

### 3. 写入配置

http 作用域示例：

```
http {
 ...
 client_max_body_size 100M;
}
```

server 作用域示例：

```
server {
 ...
 client_max_body_size 100M;
}
```

location 作用域示例：

```
location /uploads {
 ...
 client_max_body_size 100M;
}
```

数值与单位按实际业务需求填写，不要直接照搬示例值。若需完全取消限制可设为 `0`，但这会显著增加资源耗尽风险，通常不建议在生产使用。

### 4. 校验并生效

```
nginx -t
```

语法检查通过后再重载或重启：

```
systemctl reload nginx
```

或使用 SysV init 环境：

```
service nginx reload
```

重载不会中断现有连接，通常优于重启。若配置结构变化较大，可改用 `systemctl restart nginx`。

## 验证方法

- 使用小于新上限的文件上传，确认返回成功。
- 使用略大于新上限的文件上传，确认返回 413 且错误日志有对应记录。
- 检查响应头与错误日志，确认限制值已按预期生效。
- 在多个虚拟主机或目录上分别验证，确认作用域符合设计。

## 回退建议

若出现异常，恢复备份文件后重载配置：

```
cp /etc/nginx/nginx.conf.bak.[时间戳] /etc/nginx/nginx.conf
nginx -t
systemctl reload nginx
```

回退后再次验证原有上传功能是否恢复正常。

## 常见问题

- 已修改配置但仍返回 413：检查是否存在更内层的 `location` 覆盖，或上游代理、WAF、CDN 另有上限。
- 上传大文件超时而非被拒：需同时检查 `client_body_timeout`、`proxy_read_timeout` 等超时参数。
- 上传占用大量临时空间：请求体可能先写入临时目录，需关注 `client_body_temp_path` 所在分区的容量。
- 配置未生效：确认修改的是实际被加载的配置文件，可用 `nginx -T` 查看完整生效配置。

以上参数名称与行为以所用 NGINX 版本的官方文档为准。
