# Nginx上传文件大小限制完全指南 | Nginx Upload File Size Limit

> 解决"413 Request Entity Too Large"错误的详细配置方法，适用于需要上传大文件的Web应用

## 为什么会遇到Nginx上传限制问题？

默认情况下，Nginx对上传文件的大小有1MB的限制。当用户尝试上传超过此限制的文件时，会收到"413 Request Entity Too Large"错误。这个限制是Nginx的安全机制，但在合法的大文件上传场景中（如图片、视频或文档上传功能）需要适当调整。本指南将详细介绍如何修改Nginx配置以增加上传文件大小限制。

## 关键配置参数详解

要调整Nginx的上传文件大小限制，主要涉及以下参数：

| 参数名称                       | 默认值    | 作用描述             |
| -------------------------- | ------ | ---------------- |
| client\_max\_body\_size    | 1M     | 客户端请求主体的最大允许大小   |
| client\_body\_buffer\_size | 8K/16K | 读取客户端请求主体的缓冲区大小  |
| client\_body\_timeout      | 60s    | 读取客户端请求主体的超时时间   |
| client\_body\_temp\_path   | -      | 存储客户端请求主体的临时文件路径 |

## 配置方法：三种有效位置

可以在以下三个不同级别的配置块中设置上传大小限制：

### 1. 全局http配置（影响所有站点）

在Nginx配置文件`nginx.conf`的`http`块中添加：

```nginx
http {
    # 全局设置，对所有虚拟主机生效
    client_max_body_size 20M;
    client_body_buffer_size 128k;
    
    # ... 其他http配置 ...
}
```

### 2. 服务器级别配置（影响特定站点）

在特定的`server`块中添加：

```nginx
server {
    listen 80;
    server_name example.com;
    
    # 仅对此虚拟主机生效
    client_max_body_size 20M;
    client_body_buffer_size 128k;
    
    # ... 其他server配置 ...
}
```

### 3. 特定位置配置（影响特定URL路径）

在特定的`location`块中添加：

```nginx
location /upload {
    # 仅对/upload路径生效
    client_max_body_size 100M;
    client_body_buffer_size 256k;
    
    # ... 其他location配置 ...
}
```

## 应用配置的步骤

1. **编辑Nginx配置文件**

   ```bash
   sudo nano /etc/nginx/nginx.conf
   # 或编辑特定站点配置
   sudo nano /etc/nginx/sites-available/your-site
   ```
2. **添加或修改相关参数**

   根据需求在适当位置添加`client_max_body_size`和`client_body_buffer_size`配置
3. **验证配置语法**

   ```bash
   sudo nginx -t
   ```
4. **重启Nginx服务使配置生效**

   ```bash
   # 对于使用systemd的系统
   sudo systemctl restart nginx

   # 对于使用SysV的系统
   sudo service nginx restart
   ```

## 全栈配置：同步调整后端限制

仅修改Nginx配置可能不足以解决上传限制问题，还需要同步调整后端服务的相关配置：

### PHP配置调整

如果使用PHP，需要修改`php.ini`文件：

```ini
; 上传文件最大大小
upload_max_filesize = 20M

; POST请求最大大小（应大于等于upload_max_filesize）
post_max_size = 20M

; 脚本最大执行时间（秒）
max_execution_time = 300

; 脚本最大输入时间（秒）
max_input_time = 300
```

### Node.js (Express) 配置调整

```javascript
app.use(express.json({ limit: '20mb' }));
app.use(express.urlencoded({ limit: '20mb', extended: true }));
```

## 故障排除

如果配置后仍然出现413错误，请检查：

1. **确认配置应用位置正确**：对于复杂的Nginx配置，确保在正确的块中设置了参数
2. **检查后端限制**：确保PHP或其他后端服务也适当增加了限制
3. **检查临时目录权限**：确保`client_body_temp_path`指定的路径存在且有足够权限
4. **查看Nginx错误日志**：检查`/var/log/nginx/error.log`获取更多信息

## 安全注意事项

* **不要设置过大的限制**：根据实际需求设置合理的大小限制，避免服务器资源浪费和潜在的DOS攻击风险
* **考虑使用分片上传**：对于超大文件，考虑实现分片上传功能而非简单增加上传限制
* **添加文件类型验证**：在服务器端增加对上传文件类型的严格验证
* **实施速率限制**：考虑使用Nginx的`limit_req`模块对上传请求进行速率限制

***

通过以上配置，您可以有效解决Nginx上传文件大小限制问题，为用户提供更好的大文件上传体验。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://notes.ronething.cn/nginx-upload-size-limit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.