TP6.0在Nginx服务器与PHP-FPM环境下上传超时504问题解决方案

对于TP6.0项目在Nginx与PHP-FPM组合环境下上传大文件时频繁出现504 Gateway Timeout错误的问题，需要明确一点：这并非框架本身的缺陷，而是Nginx和PHP-FPM在超时配置上未能协调一致。通俗地说，请求在通信的某个环节被强制终止了——例如上传200MB文件时卡在发送阶段，Nginx尚未收到完整的响应就已放弃等待。要从根本上解决此问题，必须从三个层面同步进行优化调整。

修改 Nginx 站点配置，同步收紧三段超时

进入宝塔面板，依次点击「网站」→「对应站点」→「配置文件」，在 location ~ \.php(.*)$ 区块内、fastcgi_pass 行的正下方，添加以下三条配置：

fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;

这三个超时参数必须设为相同的数值，这一细节至关重要——切忌只修改 fastcgi_read_timeout。Nginx与PHP-FPM的通信交互分为连接(connect)、发送(send)和读取(read)三个阶段，任何一个阶段超时都会直接导致504错误。宝塔面板默认仅开放了read项的设置，而connect和send两项仍保持60秒的默认值，上传大文件时极易在send阶段卡住。修改完成后，点击右上角的「重载配置」按钮即可生效，无需选择「重启Nginx」。

放开 PHP-FPM 层的 request_terminate_timeout

接着编辑 /www/server/php/81/etc/php-fpm.d/www.conf 配置文件（请根据实际使用的PHP版本号替换目录名，例如80、82等版本遵循相同的配置逻辑）。

通过以下命令查看当前参数值：grep request_terminate_timeout /www/server/php/81/etc/php-fpm.d/www.conf

若返回结果为 request_terminate_timeout = 60，请将其修改为 request_terminate_timeout = 300，或直接将该行注释掉（注释后将以全局默认值生效，通常为0，即不设限制）。如果当前值已经是0，则可直接跳过此步骤。

保存配置文件后，执行重启命令：service php-fpm-81 restart（版本号必须与conf路径中的版本完全对应）。

这里需要重点说明：TP6框架中通过 ini_set('max_execution_time', '300') 或php.ini中的 max_execution_time 设置，在此场景下实际上并不起作用。因为这两个参数受 request_terminate_timeout 的约束，后者如果不放宽限制，前者的数值设置得再大也无济于事。

增大 Nginx fastcgi 缓冲区并确认 tmp 目录权限

在同一 location ~ \.php(.*)$ 区块中，继续添加或修正以下四项缓冲区配置：

fastcgi_buffer_size 128k;
fastcgi_buffers 4 256k;
fastcgi_busy_buffers_size 512k;
fastcgi_temp_file_write_size 512k;

如果缓冲区容量设置过小，Nginx会自动尝试将数据写入临时文件。此时若 /www/wwwroot/你的站点/tmp 目录对 www 用户缺乏写入权限，便会造成IO阻塞，最终引发超时。因此建议执行以下命令：chown -R www:www /www/wwwroot/你的站点/tmp，同时确保该目录存在且未被设置为只读状态。

若后续在错误日志中频繁看到 upstream buffer is too small 的提示信息，可以逐步适当调高这些数值，但不建议一开始就直接设置为1M这样的过大值。

补充：TP6 框架层需显式允许大文件上传

编辑 config/filesystem.php 配置文件，确认 'upload' => ['max_size' => 0] 已正确设置——0代表不对上传文件大小做任何限制。

在控制器的文件接收处理逻辑中，调用 $file->getSize() 之前，建议先执行 $file->isValid() 检查，防止因底层超时导致文件对象为空而程序仍继续执行后续操作。

此外，TP6框架默认不会对上传中断进行拦截处理。若业务场景要求强一致性，建议在上传完成后对文件进行MD5值或文件大小校验，确保与客户端传入的数据保持一致。