Laravel Horizon 需 Redis 连通、定时快照、权限放行和独立进程四者齐备，缺一导致白屏或指标失效；安装需确认 Redis 队列驱动、执行 horizon:install/migrate、启用配置、添加每分钟快照任务并确保 cron 运行。
直接上手 Laravel Horizon，不是装完就能用的“开箱即用”工具——它需要 Redis 连通、定时快照、权限放行和独立进程四者齐备，缺一就会白屏、指标不动或失败任务不显示。
安装与基础配置必须到位
先确认项目已用 Redis 作队列驱动（.env 中 QUEUE_CONNECTION=redis），再执行：
composer require laravel/horizon-
php artisan horizon:install（推荐，比vendor:publish更可靠，自动创建配置、迁移和资源软链） -
php artisan migrate（生成failed_jobs表等必要结构）
检查 config/horizon.php 中 'enabled' => true，并确认 HorizonServiceProvider 已注册在 config/app.php 的 providers 数组中。
仪表盘能访问，不代表数据在动
/horizon 页面打开只是第一步。真正让指标活起来，靠的是每分钟一次的快照采集：
立即学习“PHP免费学习笔记（深入）”；
- 在 app/Console/Kernel.php 的
schedule()方法里加：$schedule->command('horizon:snapshot')->everyMinute(); - 确保服务器 cron 正确运行：
* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1 - 手动执行
php artisan horizon:snapshot，观察是否报 Redis 连接异常——这是指标冻结最常见的根因
注意：APP_ENV=testing 下 Horizon 默认跳过快照，测试时请切到 local 或 production 环境。
看懂积压，不能只盯 Horizon 页面数字
High 优先级队列一旦积压，支付通知、风控校验等关键任务就可能超时失效。单靠 Horizon 的 “Pending jobs” 容易误判，因为它有缓存延迟（默认 5 秒刷新）：
-
查 Horizon 指标：进 high 队列详情页，看 “Recent Jobs” 列表里是否有大量
reserved_at IS NULL但available_at是 1 分钟前的任务 -
直读 Redis：用
redis-cli LLEN queues:high（注意前缀，如设了HORIZON_PREFIX=prod:，实际键是prod:queues:high） -
验证配置：确认
config/horizon.php中 supervisor 的'queue' => ['high']已明确列出，否则 Horizon 根本不监控该队列
权限与进程管理要闭环
仪表盘不是谁都能进，进程也不是启了就稳：
- 生产环境需显式放开路由：在 App\Providers\HorizonServiceProvider.php 的
boot()方法里定义授权逻辑，例如限制邮箱白名单 - Horizon 启动后必须长期运行，不能只靠
php artisan horizon手动前台启动——生产环境务必用 Supervisor 管理，配置中设autorestart=true - 更新部署后重启：用
php artisan horizon:terminate，Horizon 会优雅退出并在下次请求时自动拉起新进程，避免中断正在处理的任务
