Nginx上传大文件被拒解决方法

文章小白一枚，正在不断学习积累知识，现将学习到的知识记录一下，也是将我的所得分享给大家！而今天这篇文章《解决 fetch 上传大文件时 Nginx 被拒方法》带大家来了解一下##content_title##，希望对大家的知识积累有所帮助，从而弥补自己的不足，助力实战开发！

本文详解因 Nginx 默认限制请求体大小导致 fetch 上传大文件（如 124MB）失败的问题，重点说明如何通过配置 `client_max_body_size` 解决 `ERR_QUIC_PROTOCOL_ERROR` 或 `TypeError: Failed to fetch` 等前端静默失败现象。

当在 Laravel 应用中使用 JavaScript 的 fetch() 向 Nginx 服务器上传较大文件（例如 124MB）时，即使 PHP 层已正确配置 upload_max_filesize = 0 和 post_max_size = 0，请求仍可能在到达 PHP 或 Laravel 之前就被 Nginx 拦截——此时浏览器控制台常报 ERR_QUIC_PROTOCOL_ERROR（启用 QUIC 时）或更通用的 TypeError: Failed to fetch（禁用 QUIC 后），而 Nginx 的 access.log 中完全缺失该 POST 请求记录，error.log 也无明显报错。这正是典型的 Nginx 请求体大小限制触发的静默拒绝。

Nginx 默认的 client_max_body_size 为 1MB，远低于实际上传需求。该指令独立于 PHP 配置，作用于 HTTP 请求解析阶段，一旦请求体（即整个 multipart/form-data payload）超过此值，Nginx 会直接返回 413 Request Entity Too Large 错误——但现代浏览器（尤其是启用了 QUIC 的 Chrome）有时不会将该错误透出到 JavaScript 的 fetch().catch() 中，而是表现为连接重置或协议错误，造成调试困难。

✅ 正确解决方案是在 Nginx 配置中显式增大该限制。推荐在 server 块或更精确的 location 块中设置：

# 方式1：全局生效（适用于所有上传路径）
server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # 允许最大 256MB 请求体（根据业务调整）
    client_max_body_size 256M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

或更安全地，仅对上传接口路径生效（如 Laravel 的 API 路由）：

# 方式2：精准控制（推荐）
location ~ ^/(api|uploads) {
    client_max_body_size 256M;
    try_files $uri $uri/ /index.php?$query_string;
}

⚠️ 注意事项：

• 修改后必须重启 Nginx 才能生效：sudo systemctl reload nginx（推荐 reload，平滑重启不中断服务）；
• 若使用 location 块配置，请确保其位于 root、index 等基础指令之后，且未被其他 location 优先级更高的规则覆盖；
• client_max_body_size 0 表示不限制，但生产环境不建议设为 0，应设为略大于业务最大文件的合理值（如 512M），以防资源耗尽；
• 同时检查防火墙或 CDN（如 Cloudflare）是否也有上传大小限制，它们可能在 Nginx 前就拦截请求；
• 前端 fetch 调用建议添加超时与明确错误处理，便于定位是网络层还是应用层问题：

const formData = new FormData();
formData.append('file', fileInput.files[0]);

try {
  const res = await fetch('/api/upload', {
    method: 'POST',
    body: formData,
    // 注意：不要手动设置 Content-Type，让浏览器自动设置带 boundary
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  console.log('Upload success');
} catch (err) {
  console.error('Upload failed:', err.message); // 可捕获网络中断、CORS、413等
}

总结：PHP 配置只影响脚本执行层，而 Nginx 的 client_max_body_size 是 HTTP 协议层的第一道关卡。排查大文件上传失败时，应优先验证 Nginx 日志（开启 error_log /var/log/nginx/error.log debug; 可捕获 413 细节）、确认配置加载状态（nginx -t），再结合浏览器 Network 面板查看请求是否发出及响应状态码，从而快速定位瓶颈所在。

到这里，我们也就讲完了《Nginx上传大文件被拒解决方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！