Hyperf上传大文件失败解决方法

Hyperf上传大文件失败的根源并非FileUpload组件本身，而是Swoole HTTP Server默认仅4MB的`max_package_size`限制导致请求体未收全即被强制断连，使上传逻辑根本无法触发；解决关键是在`config/autoload/server.php`中将`max_package_size`设为足够大的字节数（如100MB），并同步调优Nginx的`client_max_body_size`和FileUpload的`max_size`配置，三者缺一不可——否则即使修改一处，仍会静默失败，表现为前端网络错误、服务端零日志、curl卡住等典型现象，务必重启服务生效。

Hyperf 的 FileUpload 上传大文件失败，根本原因通常不是 FileUpload 组件本身，而是 Swoole HTTP Server 的 max_package_size 限制被触发了 —— 默认仅 4MB，超限后连接直接断开，连请求体都收不全，自然没法走到上传逻辑。

为什么改 max_package_size 才管用？

Hyperf 基于 Swoole HTTP Server，所有 HTTP 请求（包括 multipart/form-data）都先由 Swoole 接收并缓存。Swoole 在解析完整个 HTTP 包前，会校验总包大小是否超过 max_package_size。一旦超限，立刻关闭连接，返回空响应或 400 错误（有时甚至无响应），FileUpload 根本没机会执行。

常见现象包括：

• 前端 fetch 或 axios 报 Network Error 或 ERR_CONNECTION_RESET
• Hyperf 日志里完全看不到请求进来的痕迹（AccessLog 和中间件日志均为空）
• 用 curl -v 测试时卡在 Waiting for response 后直接断连

在哪里设置 max_package_size？

必须在 Swoole Server 初始化阶段设置，即 config/autoload/server.php 的 settings 数组中，不能在中间件、控制器或 FileUpload 配置里改。

示例配置（支持 100MB 文件）：

'settings' => [
    'max_package_size' => 100 * 1024 * 1024, // 单位：字节
    // 其他 settings...
],

注意：

• 值必须是整数，单位为字节；写成 100 * 1024 * 1024 比硬编码 104857600 更可读且不易出错
• 该配置影响所有 HTTP 请求（不仅是上传），设得过大可能增加内存压力，但对现代服务器影响有限
• 修改后必须重启服务：php bin/hyperf.php start，热重载不生效

还要同步检查的几个关键点

max_package_size 是前提，但不是唯一条件。以下任一未调优都会导致上传失败：

• upload_max_filesize 和 post_max_size（PHP-FPM 场景才需关注；Hyperf 直连 Swoole 时**不经过 PHP ini**，此项可忽略）
• client_max_body_size（Nginx 反向代理时必须同步调整，否则 Nginx 在请求到达 Hyperf 前就拦截了）
• FileUpload 的 max_size 配置（这是应用层校验，单位是字节，例如 100 * 1024 * 1024，它只在 Swoole 成功接收后才生效）
• 超时设置：大文件上传慢，还需增大 request_timeout（Swoole）和 timeout（Nginx）

真正容易被忽略的是：Nginx 的 client_max_body_size 和 Swoole 的 max_package_size 必须一致或前者 ≥ 后者。两者只要有一个卡住，上传就静默失败，而且错误表现几乎一样 —— 看不到日志、没有堆栈、前端只有网络错误。

本篇关于《Hyperf上传大文件失败解决方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！