Laravel Horizon 404 错误排查与本地环境路由启用指南-php教程-PHP中文网

Laravel Horizon 404 错误排查与本地环境路由启用指南

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（本地环境自动放行）
你自定义的 viewHorizon Gate 在 APP_ENV=local 下完全被忽略——Horizon 会跳过授权检查直接允许访问。因此你的权限逻辑此时不生效，也无需修改 HorizonServiceProvider。如需本地调试权限逻辑，可临时注释掉 parent::boot() 后的自动逻辑，但更推荐保持默认行为。
启动 Horizon 进程并验证

Laravel Creem Agent
Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载
```
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 路由 + 浏览器可访问 → 即配置完成。