<p>根本原因是Swoole的max_package_size默认仅2MB被触发，导致请求体未收全即断连；需在config/autoload/server.php中配置'max_package_size' => 100 1024 1024，并同步调整Nginx的client_max_body_size及FileUpload的max_size。</p>
Hyperf 项目里文件上传超时，**根本不是“超时”问题，而是请求体被截断或直接拒绝**——你看到的“超时”，大概率是 Swoole 拒绝接收完整请求包后客户端卡住、Nginx 返回 413、或者 PHP 根本没收到 $_FILES。必须分清底层拦截点，否则改 max_execution_time 或 set_time_limit() 完全无效。
为什么改 php.ini 的 upload_max_filesize 没用？
Hyperf 直连 Swoole，不走 PHP-FPM，所以 upload_max_filesize 和 post_max_size 这两个 ini 配置**完全不生效**。Swoole 在 HTTP 解析前就按自己的缓冲区上限做校验，PHP 层根本收不到数据。
- 现象：前端报
ERR_CONNECTION_RESET或空响应，Hyperf 日志里压根没有该请求记录 - 错误日志里可能看到：
Request Entity Too Large: header-length (xxx) + content-length (yyy) is greater than the package_max_length(zzz) - 别查
phpinfo()里的 Loaded Configuration File——它和 Hyperf 运行时无关 - 唯一有效的配置入口是
config/autoload/server.php里的settings数组
必须调大 Swoole 的 package_max_length（即 max_package_size）
这个值控制 Swoole HTTP Server 单次接收的完整 HTTP 包最大字节数，默认仅 2097152（2MB），上传大文件必然触发截断。
- 在
config/autoload/server.php的'settings' => []中添加：'max_package_size' => 100 * 1024 * 1024,（支持 100MB） - 注意：键名是
max_package_size，不是package_max_length（后者是旧版 Swoole 4.4 之前的写法，Hyperf 3.0+ 已弃用） - 值必须是整数，单位字节；写成
100 * 1024 * 1024比硬编码104857600更安全可读 - 修改后必须执行
php bin/hyperf.php start重启服务，热重载不生效
同步检查 Nginx 和 Hyperf FileUpload 组件配置
max_package_size 是前提，但漏掉任一环节都会失败：
立即学习“PHP免费学习笔记（深入）”；
- Nginx 反向代理时，
client_max_body_size必须 ≥ Swoole 的max_package_size，否则在到达 Hyperf 前就被 Nginx 拒绝并返回 413 - Hyperf 的
FileUpload配置中max_size也得同步放大，否则组件层会主动抛出FileTooLargeException - 如果上传路径涉及临时目录（如
/tmp），确认磁盘空间和写权限充足，否则上传中途会静默失败 - 超大文件上传耗时长，还需调高 Swoole 的
request_timeout（比如设为300），避免握手或解析阶段被判定超时
别忽略客户端和网络中间件的超时限制
即使服务端全调通，前端 fetch 或 axios 默认 timeout 是 0（无限），但实际受浏览器/OS TCP 层影响；更常见的是云厂商 LB（如阿里云 SLB、腾讯云 CLB）默认 60 秒空闲超时，会直接断开长连接。
- 前端建议显式设
timeout: 300000（5 分钟） - 云环境必须加应用层心跳帧（比如每 30 秒发一次 ping），不能只依赖 TCP KeepAlive
- 若用 Postman 测试，关掉 “Automatically persist cookies” 和 “Send no-cache header”，避免额外头导致包体超标
真正卡住上传的，往往不是某个单一配置，而是 Swoole 缓冲区、反向代理限制、组件校验、客户端行为四层叠加的结果。调试时优先看 Swoole 错误日志里的 package_max_length 提示，再逐层向上排查，比盲目调大所有 timeout 更高效。
