Laravel Horizon 安装后访问 /horizon 返回 404，且 php artisan route:list 中无相关路由——常见原因包括服务提供者未正确注册、缓存未刷新、环境配置冲突或自动发现机制失效；本文提供系统性诊断与修复步骤。
laravel horizon 安装后访问 `/horizon` 返回 404，且 `php artisan route:list` 中无相关路由——常见原因包括服务提供者未正确注册、缓存未刷新、环境配置冲突或自动发现机制失效；本文提供系统性诊断与修复步骤。
Laravel Horizon 是 Laravel 官方提供的 Redis 驱动队列监控面板，其 Web 路由默认由 Laravel\Horizon\HorizonServiceProvider 自动注册。当访问 /horizon 出现 404 且 route:list 中完全缺失 Horizon 路由时，说明该服务提供者根本未被加载或路由注册逻辑被跳过，而非权限或中间件问题。
✅ 首要检查：服务提供者是否启用
Horizon 的服务提供者需显式注册（Laravel 9+ 默认启用包自动发现，但仍可能失效）。请确认 config/app.php 中的 providers 数组包含：
// config/app.php
'providers' => [
// ... 其他服务提供者
Laravel\Horizon\HorizonServiceProvider::class,
],
⚠️ 注意：若你已自定义 HorizonServiceProvider（如继承 HorizonApplicationServiceProvider 并重命名），必须手动注册该自定义类，而非原生 HorizonServiceProvider。你当前的 App\Providers\HorizonServiceProvider 是正确的扩展方式，但需确保它已被注册：
// config/app.php
'providers' => [
// ... 其他
App\Providers\HorizonServiceProvider::class, // ✅ 关键：注册你的自定义提供者
],
? 强制刷新应用状态
自动发现失败或配置缓存残留是本地开发中最常见的“幽灵故障”。执行以下命令按顺序彻底清理：
php artisan config:clear php artisan cache:clear php artisan route:clear php artisan view:clear composer dump-autoload
? 提示：重启 PHP 开发服务器（如
php artisan serve）或 Web 服务器（Nginx/Apache）后，再测试/horizon。
? 环境与路由注册逻辑验证
Horizon 的路由仅在以下条件满足时注册：
- 应用处于
local或testing环境 或 -
Horizon::routes()显式调用（通常由服务提供者完成）
检查 .env 文件确认：
APP_ENV=local
若为 production，则必须通过 Gate 授权（你已实现），但本地环境应完全绕过 Gate 检查——因此你的 gate() 方法在本地实际不会被调用，无需修改。确保未意外将 APP_ENV 设为 production。
? 验证 Horizon 是否真正集成
运行以下命令确认 Horizon 已被 Composer 正确识别：
composer show laravel/horizon
输出应显示已安装版本（如 v5.21.0）。若无输出，请重新执行：
composer require laravel/horizon php artisan horizon:install
⚠️
horizon:install会发布配置、迁移和资源，必须成功执行且无报错。
? 最终验证与调试技巧
若上述步骤仍无效，可临时添加调试代码至 App\Providers\HorizonServiceProvider::boot()：
public function boot()
{
\Log::info('HorizonServiceProvider booting...');
parent::boot();
}
然后访问任意页面并检查 storage/logs/laravel.log —— 若无该日志，证明服务提供者根本未加载，需回查 config/app.php 注册项。
✅ 总结：关键动作清单
| 步骤 | 操作 |
|---|---|
| ✅ 1 | 在 config/app.php 中注册 App\Providers\HorizonServiceProvider::class
|
| ✅ 2 | 运行 php artisan config:clear && php artisan route:clear && composer dump-autoload
|
| ✅ 3 | 确认 .env 中 APP_ENV=local 且 APP_DEBUG=true
|
| ✅ 4 | 重启开发服务器（php artisan serve 需重新启动） |
| ✅ 5 | 访问 http://your-app.test/horizon（注意：不带 https 的本地 URL 更可靠） |
? 补充说明：正如问题作者所经历的——有时简单重启开发环境（包括电脑休眠/唤醒）即可解决因文件监听器、OPcache 或 Redis 连接状态导致的瞬时注册失败。这不是玄学，而是底层资源状态同步的典型表现。
完成以上任一环节后，php artisan route:list | grep horizon 应输出类似：
| GET|HEAD | horizon | horizon.dashboard | Laravel\Horizon\Http\Controllers\DashboardController@index | web,auth | GET|HEAD | horizon/api/... | horizon.api.metrics | Laravel\Horizon\Http\Controllers\MetricsController@metrics | api,auth
此时 /horizon 即可正常访问，进入可视化队列监控面板。
