Horizon可实时监控Laravel文件处理队列状态。需安装Horizon、正确配置Redis、在config/horizon.php中为files队列设置专用supervisor，并通过onQueue()或$queue属性投递任务，最后通过Horizon Web界面排查失败或卡住任务。
你需要实时查看Laravel应用中文件处理类队列（如PDF生成、Excel导出、图片压缩）的运行状态、延迟任务数、失败重试次数，避免用户上传后长时间无响应或任务静默失败。
安装并启用Horizon
在已配置好Redis作为队列驱动的Laravel项目根目录执行：composer require laravel/horizon。
运行php artisan horizon:install，该命令会发布配置文件config/horizon.php并注册服务提供者。
Horizon依赖Redis连接，【必须确保.env中REDIS_HOST、REDIS_PORT、REDIS_PASSWORD（如有）配置正确且Redis服务正在运行】，否则后续所有界面均无法加载数据。
配置文件处理专用队列
打开config/horizon.php，定位到environments → production（或local）下的supervisors数组。
新增一个名为files的supervisor，指定其监听files队列，并限制并发为3：
'files' => ['connection' => 'redis', 'queue' => ['files'], 'balance' => 'simple', 'processes' => 3, 'tries' => 3],
这一步必须做——如果不单独划分队列，文件处理任务会和邮件、通知等混在一起，监控时无法快速识别瓶颈；同时tries设为3可防止因临时IO错误导致的无限重试。
启动Horizon并开放Web界面
执行php artisan horizon启动守护进程，它会自动读取config/horizon.php中的supervisor配置。
默认情况下Horizon Web界面仅在APP_ENV=local时开放，若需在测试环境访问，修改app/Providers/HorizonServiceProvider.php中的gate方法：将return true;替换为return app()->environment('local', 'staging');。
访问http://your-app.test/horizon，登录后即可看到实时仪表盘，左侧导航栏点击“Queues”→选择“files”，立即显示当前积压任务数、平均耗时、最近失败记录。
在代码中投递文件处理任务到指定队列
方法一：使用onQueue()显式指定
ProcessUploadedFile::dispatch($file)->onQueue('files');
方法二：在Job类中重写$queue属性
class ProcessUploadedFile implements ShouldQueue { public $queue = 'files'; }
方法三：全局绑定队列名（推荐用于统一管控）
在AppServiceProvider的boot()中添加：Queue::after(function (JobProcessed $event) { if (str_contains($event->job->job, 'ProcessUploadedFile')) { $event->connection->setQueue('files'); } }); —— 此方式不推荐，因JobProcessed事件发生在执行后，无法影响投递时的队列选择，纯属干扰项，删掉。
真正生效的是前两种。注意：如果Job类里同时定义了$queue属性又调用onQueue()，后者优先级更高。
排查文件任务卡住的典型路径
第一步：打开Horizon界面 → 点击顶部“Failed”标签页 → 筛选Queue为“files” → 查看最近失败任务的异常堆栈。
第二步：若失败任务为空但任务长时间未完成，切换到“Jobs”标签页 → 点击“Recent” → 按Started时间倒序 → 找出运行超5分钟的任务 → 点击ID查看原始payload和日志上下文。
第三步：确认该任务是否触发了阻塞式文件操作（如file_get_contents('http://...')未设超时），这类操作会让Worker进程挂起，导致整个files队列停滞——【必须改用Guzzle异步请求或加try/catch+超时控制】。
