Laravel Horizon 安装后访问 /horizon 返回 404，且 php artisan routes:list 中无相关路由——常见原因包括服务提供者未正确注册、缓存未刷新、环境配置冲突或框架热加载异常，重启开发环境常可解决。
laravel horizon 安装后访问 `/horizon` 返回 404，且 `php artisan routes:list` 中无相关路由——常见原因包括服务提供者未正确注册、缓存未刷新、环境配置冲突或框架热加载异常，重启开发环境常可解决。
Laravel Horizon 是 Laravel 官方提供的 Redis 队列监控仪表板，但其路由并非默认全局启用，而是依赖服务提供者自动注册与环境感知机制。即使 Horizon 进程运行正常（php artisan horizon:status 显示 “Horizon is running”），若 Web 请求路由未加载，仍会返回 404。
✅ 正确启用步骤（Laravel 9+）
-
确认 HorizonServiceProvider 已注册
安装后，laravel/horizon应自动将Laravel\Horizon\HorizonServiceProvider注册到config/app.php的providers数组中（Laravel 9+ 使用自动发现，通常无需手动添加）。请检查：grep -r "HorizonServiceProvider" config/app.php
若未找到，请手动在
config/app.php的providers中添加：Laravel\Horizon\HorizonServiceProvider::class,
确保 Horizon 路由被加载
Horizon 的路由定义在Laravel\Horizon\Horizon::routes()中，由HorizonApplicationServiceProvider在boot()阶段调用。关键前提：该服务提供者必须被启用且未被条件屏蔽。
默认情况下，Horizon 仅在APP_ENV=local或通过授权门面（Gate）放行时注册路由。你已自定义了gate()方法，但请注意：本地环境（APP_ENV=local）下，Horizon 会跳过 Gate 检查并强制注册路由 —— 因此你的权限逻辑此时不生效，也不应影响路由注册。-
清除全部缓存并重载配置
执行以下命令（顺序不可颠倒）：php artisan config:clear php artisan cache:clear php artisan route:clear php artisan view:clear composer dump-autoload
⚠️ 注意：仅
route:clear不足以解决问题，config:clear和cache:clear同样关键，因 Horizon 的启用状态受config/horizon.php及应用缓存影响。 -
验证 APP_ENV 配置
确保.env中明确设置：APP_ENV=local
若为
APP_ENV=production或其他值，Horizon 将严格依赖Gate::define('viewHorizon')，且必须返回true才注册路由（即使你已登录用户）。此时请确保中间件Horizon\Http\Middleware\Authorize被正确应用（它由 Horizon 自动注册）。 -
检查路由是否实际存在
清除缓存后，重新列出路由：php artisan route:list | grep horizon
成功时应看到类似输出：
GET|HEAD horizon ... Laravel\Horizon\Http\Controllers\DashboardController@index
? 补充说明：关于你的自定义 HorizonServiceProvider
你继承 HorizonApplicationServiceProvider 并重写 gate() 是正确的做法（尤其集成 Spatie Permissions 时）。但需注意：
-
boot()方法中必须调用parent::boot()（你已做到），否则路由注册逻辑不会执行； - 本地环境下，
Horizon::routes()内部会直接注册路由，不调用gate()，因此你的权限逻辑此时不参与路由加载，仅影响后续页面访问控制。
✅ 最终验证
启动队列监听器与 Horizon 服务：
php artisan horizon # 在后台运行（推荐使用 supervisor 或 `php artisan horizon &`）
然后访问 http://your-app.test/horizon（确保使用与 APP_URL 一致的域名，避免跨域或重定向问题）。
? 经验提示：如遇“玄学失效”，执行
php artisan serve重启开发服务器，或彻底重启终端/IDE（尤其使用 Sail/Valet/Docker 时）。正如提问者所经历的——周末关机后重启，环境状态重置，问题自然消失。这印证了 Laravel 应用缓存与服务热加载可能引发的瞬时不一致问题。
至此，Horizon 路由应正常响应，仪表板可访问。
