Laravel Horizon 安装后访问 /horizon 返回 404，且 php artisan routes:list 中无相关路由——常见原因包括服务提供者未正确注册、应用缓存未刷新、或 Horizon 未在当前环境启用。本文详解完整配置流程与关键排查步骤。
laravel horizon 安装后访问 `/horizon` 返回 404，且 `php artisan routes:list` 中无相关路由——常见原因包括服务提供者未正确注册、应用缓存未刷新、或 horizon 未在当前环境启用。本文详解完整配置流程与关键排查步骤。
Laravel Horizon 是 Laravel 官方提供的 Redis 驱动队列监控仪表板，但其 Web 路由默认仅在非生产环境（如 local、development）自动注册，且依赖多个前提条件才能生效。即使 php artisan horizon:status 显示 “Horizon is running”，也不代表 Web 界面已就绪——因为 Horizon 的 HTTP 路由由 HorizonServiceProvider 动态注册，而非通过常规 routes/web.php 声明。
✅ 正确启用 Horizon Web 路由的必要步骤
-
确认 HorizonServiceProvider 已注册
检查config/app.php的providers数组中是否包含：Laravel\Horizon\HorizonServiceProvider::class,
⚠️ 注意：
horizon:install命令不会自动注册服务提供者（Laravel 9+ 使用自动发现，但需确保composer.json中"laravel/horizon"在require区且已执行composer dump-autoload）。若手动注册，请勿重复添加。 -
清除所有缓存（关键！）
Horizon 路由注册受 Laravel 应用缓存影响。务必依次执行：php artisan config:clear php artisan cache:clear php artisan route:clear php artisan view:clear composer dump-autoload
? 这是多数“404 且无路由”问题的根源——尤其是开发中频繁修改配置后未清缓存。
-
验证 APP_ENV 配置
Horizon 默认仅在APP_ENV=local（或testing、development）时启用 Web 路由。检查.env：APP_ENV=local
若为
production，需显式启用（不推荐本地外使用）：// 在 app/Providers/HorizonServiceProvider.php 的 boot() 中 Horizon::routeMiddleware(['web']); Horizon::useFrontendAssets();
无需手动定义 Gate（本地环境自动放行）
你自定义的viewHorizonGate 在APP_ENV=local下完全被忽略——Horizon 会跳过授权检查直接允许访问。因此你的权限逻辑此时不生效，也无需修改HorizonServiceProvider。如需本地调试权限逻辑，可临时注释掉parent::boot()后的自动逻辑，但更推荐保持默认行为。-
启动 Horizon 进程并验证
php artisan horizon # 启动守护进程（另开终端） # 或后台运行：php artisan horizon &
再访问
http://your-app.test/horizon（注意：必须是 HTTP，非 HTTPS 测试环境；若用 HTTPS 请确保证书有效且APP_URL配置正确）。
? 快速验证路由是否注册
运行以下命令，搜索 Horizon 相关路由：
php artisan route:list | grep horizon
正常应输出类似：
| GET|HEAD | horizon | horizon.index | Laravel\Horizon\Http\Controllers\DashboardController@index | web,auth | GET|HEAD | horizon/api/... | ... | ... | web,auth
? 总结与最佳实践
- Horizon 的 Web 界面路由由服务提供者动态注册，严重依赖缓存状态——
php artisan optimize:clear或重启服务器后务必清缓存。 - 本地开发请严格使用
APP_ENV=local，避免手动干预 Gate。 - 若仍 404，检查
storage/logs/laravel.log是否有HorizonServiceProvider加载失败日志。 - 最终验证：
php artisan horizon:status显示运行中 +route:list包含 horizon 路由 + 浏览器可访问 → 即配置完成。
✅ 提示：你提到“周末重启后恢复正常”，这正是典型缓存残留问题——系统重启清除了 OPcache 和 Laravel 缓存，间接触发了正确加载。今后建议将
php artisan optimize:clear加入部署/启动脚本。
