如何通过设置Nginx的Client-Max-Body-Size参数来限制上传文件的最大大小？

本文共计623个文字，预计阅读时间需要3分钟。

在Nginx中，限制客户端上传文件大小，核心是通过以下指令控制：

确认指令名称和作用范围

client_max_body_size 是 Nginx 内置指令，影响所有含请求体的请求（如 POST、PUT）。它可出现在以下三个层级：

• http 块：全局生效，作为默认值
• server 块：覆盖 http 级设置，适用于某个域名或监听端口
• location 块：最细粒度控制，例如只对 /upload 路径放宽限制

基本配置写法

单位支持 k（KB）、m（MB）、g（GB），不加单位默认为字节。常见写法示例：

http { client_max_body_size 10m; # 全局默认 10MB server { listen 80; server_name example.com; <pre class="brush:php;toolbar:false;"> # 对整个站点使用 20MB 上限 client_max_body_size 20m; location /api/upload { # 仅此接口允许 100MB client_max_body_size 100m; } location /static { # 静态资源不需要上传，可设小一点或禁用 client_max_body_size 1m; } }

}

上传超限时的行为

当请求体超过设定值，Nginx 会直接返回 413 Request Entity Too Large 错误，且不会将请求转发给后端（如 PHP-FPM、Node.js）。这是关键点：限制发生在 Nginx 层，后端无需重复校验（但建议仍做二次防护以防绕过）。

你可以自定义错误页提升体验：

error_page 413 /413.html; location = /413.html { internal; root /usr/share/nginx/html; }

配合其他上传相关设置

单设 client_max_body_size 不足以应对所有上传场景，还需注意：

• client_body_timeout：设置读取请求体的超时时间（默认 60s），大文件上传需适当调高
• client_body_buffer_size：内存缓冲区大小，太小会导致频繁写临时文件；一般设为 128k 或 256k
• client_max_temp_file_size：上传中临时文件最大尺寸（默认 1G），若用到磁盘缓存需检查
• 确保后端（如 PHP 的 upload_max_filesize 和 post_max_size）设置 ≥ Nginx 的值，否则后端会拦截并报错

配置完记得重载 Nginx：nginx -t && nginx -s reload，避免语法错误导致服务中断。