如何在Laravel中处理长任务以避免触发504错误?
长耗时任务触发504的根因与正确处理方案
为什么你之前的配置完全没生效
你之前调整的ini_set('max_execution_time', 300)、set_time_limit(0),甚至未配对正确的Nginx超时配置,本质上根本没触碰到504的触发根源:
- 504是网关超时,代表Nginx在等待PHP-FPM返回完整响应的过程中,超过了自身预设的等待阈值,直接主动断开了TCP连接,这个判断逻辑和PHP脚本自身的执行超时设置完全无关
- 就算PHP被设置为无限制执行时间,只要Nginx、中间CDN、负载均衡某一层等不到完整响应主动掐断连接,请求还是会直接报504
- 脚本里写的
ini_set很多时候根本不生效:如果PHP配置了安全模式、或者php-fpm的全局request_terminate_timeout设了强制终止阈值,脚本运行到对应时间就会被直接杀掉,根本不会读你在脚本里写的执行时间配置。
生产环境处理长耗时任务的正确思路
真正能稳定扛住长任务、不频繁出504的方案,从来不是让请求挂着等任务跑完,而是把「同步等待任务执行」改成「异步解耦」的架构,根据不同场景适配:
1. 大查询遍历/批量导出(比如10万行结果处理)
- 不要在单个HTTP请求里同步跑完整个处理流程。收到请求后立刻生成一个唯一的任务ID,把任务描述扔进后台进程队列,马上给客户端返回202状态码,告知「任务已受理,可凭ID查询进度」
- 独立的后台工作进程负责跑长任务,每处理完一小段逻辑就把进度(已处理行数、完成占比、错误信息)写到本地缓存或者Redis里
- 客户端每隔1-2秒带着任务ID轮询一次进度,等拿到100%完成的标识,再直接拉取最终生成的结果文件。这种模式根本不会触发504,因为整个受理请求从接收到返回只需要几十毫秒,完全在所有层的超时阈值内,就算服务端临时重启,任务状态存在持久化存储里也不会丢。
2. 大文件分块上传
- 分块上传本身的设计就是把大文件拆成多个独立的短请求,只要把单个分块控制在2-5MB大小,单块传输时间在1-2秒内,根本不会触发超时
- 之前出现的504问题,本质是单块设置过大、传输时间超过了网关的等待阈值,只要调整分块大小、单独给上传接口配置适配的超时参数,就能解决。
单请求保活实现:边跑任务边推心跳不中断脚本
你之前的误区是觉得「只要给客户端发了响应,脚本就会终止运行」——实际上只要不主动调用exit、die这类终止脚本的方法,手动把缓冲区的内容推给客户端之后,PHP脚本完全可以继续往下跑,不会因为推送了部分内容就停止执行,这种方式可以用来给客户端和网关持续发心跳,避免连接被掐断。
PHP环境的具体实现步骤
- 先清空所有层级的输出缓冲,关闭自动攒包的逻辑:
- 调用
ob_end_clean()清空PHP内置的输出缓冲 - 调用
ob_implicit_flush(true),让后续所有输出不经过缓冲直接推给客户端
- 调用
- 提前给客户端设置响应头,告知这是持续输出的流内容:
header('Content-Type: text/event-stream'); header('Cache-Control: no-cache'); header('Connection: keep-alive'); - 在任务的循环逻辑里,每处理完一小段(比如1000行查询结果、1个上传分块),就往输出里写一段进度提示,再调用
flush()把这段内容立刻推出去 - 推送完进度之后不要退出,直接继续跑下一段循环就行。客户端会持续收到进度消息,Nginx会因为有持续的数据流传输,不会判定这个请求超时、主动触发504。
注意:这种单请求保活的方案只适合30秒以内的短耗时任务,绝对不适合跑几分钟以上的重型长任务。长时间占用PHP-FPM的工作进程,会快速耗尽连接池,导致站点其他正常请求都没法分配到进程处理;而且如果中间经过CDN、负载均衡层,这些层如果开了代理缓冲,你推的心跳数据会被攒在网关层,根本到不了客户端,保活效果完全失效。
必须避的坑
- 不要只在脚本里写
set_time_limit(0):要直接修改php.ini、php-fpm的全局配置文件,确认max_execution_time、request_terminate_timeout的参数和你的需求匹配,否则脚本里的临时修改很容易被上层全局配置覆盖 - 对应长任务的Nginx location配置一定要关掉代理缓冲,把
fastcgi_read_timeout、proxy_read_timeout按实际需求调整:如果开着代理缓冲,你推的心跳全被Nginx存在本地,根本不会发给客户端,等攒够超时阈值还是会断连 - 不要为了避免504把全链路的超时时间拉到无限长:重型长任务一定要走异步队列方案,单请求保活只是临时的过渡方案,长期用会把服务的连接资源彻底耗光。
内容的提问来源于stack exchange,提问作者absolutkarlos
相关产品推荐
相关产品推荐

