Nginx 中 `client_max_body_size` 限制文件上传的设置方法-Nginx-PHP中文网

必须在location块中显式配置client_max_body_size，因其优先级最高；还需同步调大client_body_buffer_size、确保client_body_temp_path权限正确、延长proxy_read_timeout等超时参数，并校准后端限制与请求头缓冲，否则仍会因缓冲、权限、超时或头部过大导致413/500/502/400错误。

nginx 中 `client_max_body_size` 限制文件上传的设置方法

client_max_body_size 是 Nginx 控制请求体大小的核心参数，直接决定文件上传能否通过第一道关卡。它不解决全部问题，但设错位置或漏配关联项，上传必然失败。

必须写在匹配路径的 location 块里

Nginx 配置遵循“location > server > http”的优先级规则。即使你在 server 块设了 `100M`，如果上传请求实际命中的是 `/api/upload` 这个路径，而该路径下没有显式配置，Nginx 就可能沿用默认的 `1M` 或其他继承值，导致 413 错误。

✅ 推荐写法：在具体转发路径中设置

location /api/upload {
    client_max_body_size 500m;
    proxy_pass http://backend;
}

❌ 常见错误：只在 http 或 server 块设值，却没覆盖到实际上传路径
⚠️ 慎用：在 server 块统一设大值，会让所有 POST 请求（如登录、表单提交）都放宽限制，增加潜在风险

单位写法与数值建议

参数值支持 `k`、`m`、`g` 单位（大小写不敏感），不加单位默认为字节。

常用写法：100m、2g、512k
0 表示禁用检查（生产环境慎用，需后端有严格校验兜底）
数值应略大于后端限制（如 PHP 的 post_max_size），建议多留 10–20MB 余量

配套参数缺一不可

`client_max_body_size` 只管“让不让进”，真正影响上传稳定性的还有三项：

client_body_buffer_size：内存缓冲区大小，推荐 512k～1m；太小会频繁刷盘，太大浪费内存
client_body_temp_path：临时文件路径，确保磁盘空间充足，且 Nginx 运行用户（如 www-data）有读写权限
proxy_read_timeout 和 proxy_send_timeout：建议设为 3600（1 小时），避免大文件传输中途超时断连

这些参数需和 client_max_body_size 写在同一作用域（例如同在 /api/upload 的 location 块内），否则无法协同生效。

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

后端限制必须同步放开

Nginx 放行后，请求才会到达后端。若后端仍有硬限制，会出现 502、500 或静默失败：

PHP（含 ThinkPHP）：调整 php.ini 中
upload_max_filesize = 500M
post_max_size = 512M（必须 ≥ upload_max_filesize）
memory_limit = 600M
修改后需重启 PHP-FPM，不是重载 Nginx

Spring Boot：在 application.yml 中设

spring:
  servlet:
    multipart:
      max-file-size: 500MB
      max-request-size: 500MB

Node.js（Express + Multer）：
app.use(upload.single('file')); 需配合 limits: { fileSize: 500 * 1024 * 1024 }

还要留意 CDN 或云负载均衡器（如阿里云 SLB、Cloudflare）是否设置了独立的请求体限制，它们的配置优先于 Nginx，需一并调大。

验证是否生效

- 执行 `nginx -t` 检查语法，再 `nginx -s reload` 重载配置 - 用 curl 测试边界值： `curl -F "file=@test.zip" http://your-domain.com/api/upload` - 查看 Nginx 错误日志：`tail -f /var/log/nginx/error.log` - 若出现 `413 Request Entity Too Large`，说明仍被拦截；若报 `500` 或连接中断，则大概率是缓冲、权限或超时问题

不复杂但容易忽略