Horizon安装失败主因是版本不兼容,需严格匹配Laravel主版本与Horizon版本;仪表盘空白因未执行horizon:install或Redis配置错误;任务不显示因未通过horizon命令启动Worker;性能问题多由trim策略未调优或日志级别过高导致。

Horizon 安装失败:composer require 报错 laravel/horizon 不兼容当前 Laravel 版本
Horizon 对 Laravel 主版本和 PHP 版本有硬性要求,不是“装了就能用”。Laravel 10 需要 Horizon v5+,Laravel 9 对应 Horizon v4,而 Laravel 8 只能用 Horizon v3 —— 混搭直接触发 require 冲突或 Class not found 错误。
实操建议:
- 先运行
php artisan --version确认 Laravel 版本,再查 Horizon 官方兼容表,严格匹配版本号 - 执行前清掉旧锁:
rm composer.lock && rm -rf vendor/,再跑composer require laravel/horizon:^v5.0(把v5.0换成你确认的精确小版本) - 如果项目用了
phpunit/phpunit低版本(如 9.x),Horizon v5 可能因依赖phpunit:^10.0报错,这时得先升测试套件,或降级 Horizon 到 v4.5(仅限 Laravel 9)
Horizon 启动后打不开 / 仪表盘空白:没跑 php artisan horizon:install 或 Redis 配置错
Horizon 不是装完就自动开 Web 界面的。它依赖 horizon:install 命令生成路由、配置和前端资源;同时必须确保 config/database.php 中的 redis 连接可用,且 config/horizon.php 的 use 字段指向正确的 Redis 连接名(默认是 default)。
实操建议:
- 装完立即执行
php artisan horizon:install,它会发布routes/horizon.php并复制前端 assets 到public/vendor/horizon - 检查
config/horizon.php中的'use' => 'default'是否和config/database.php里redis.default配置一致;若你用的是cache连接,这里也得同步改 - Redis 密码、端口、DB 编号写错会导致页面加载一半卡住,打开浏览器 DevTools → Network 标签,看
/horizon/api/metrics是否返回 500 或空响应;用redis-cli -h 127.0.0.1 -p 6379 -a yourpass ping手动测连通性
任务进队列但 Horizon 里不显示:没配 HORIZON_PREFIX 或没启用 supervisor 监控
Horizon 的仪表盘只展示它自己启动的 Worker 拉取的任务。如果你用 php artisan queue:work 手动跑,或者 Supervisor 没指向 php artisan horizon,那任务虽然进了 Redis,Horizon 根本不知道——它只监听自己创建的连接和 key 前缀。
实操建议:
- 确保所有队列消费都通过
php artisan horizon启动(开发环境可直接跑,生产必须用 Supervisor 管理) - 检查
.env是否设置了HORIZON_PREFIX=horizon:,且这个前缀没被其他进程复用;不同环境建议加环境标识,比如HORIZON_PREFIX=horizon_staging: - Supervisor 配置里 command 必须是
php /var/www/yourapp/artisan horizon,不能是queue:work;同时确认numprocs=1(Horizon 自己管理多进程,起多个实例会冲突)
Redis 内存暴涨、Horizon 响应变慢:没调 trim 策略或日志级别太高
Horizon 默认每分钟保存一次任务快照到 Redis,长期不清理会导致 horizon:metrics、horizon:recent 这类 key 持续膨胀,尤其在高频短任务场景下,可能占几个 GB。另外,LOG_LEVEL=debug 会让 Horizon 把每个任务入队/完成都写日志,进一步拖慢 Redis 写入。
实操建议:
- 在
config/horizon.php的environments下调整trim参数,例如:'recent' => 60, 'failed' => 1000, 'completed' => 1000(单位:条数),避免无限制堆积 - 生产环境务必设
LOG_LEVEL=error或warning,debug只用于排查问题时临时开启 - 定期用
redis-cli --scan --pattern "horizon:*" | wc -l查 key 总量,超 10 万条就得检查 trim 是否生效或是否有异常重试风暴
Horizon 的核心逻辑藏在 Redis key 结构和 Worker 生命周期里,表面点点点就能用,但一旦队列规模上来,trim 阈值、prefix 隔离、Supervisor 进程模型这三处最容易漏掉,一漏就是内存告警或监控失灵。


















