Laravel Horizon 路由 404 问题排查与解决方案-php教程-PHP中文网

Laravel Horizon 路由 404 问题排查与解决方案

Laravel Horizon 安装后访问 /horizon 返回 404，且 php artisan routes:list 中无相关路由——常见原因包括服务提供者未正确注册、缓存未刷新、环境配置冲突或自动发现机制失效，需系统性验证与清理。

laravel horizon 安装后访问 `/horizon` 返回 404，且 `php artisan routes:list` 中无相关路由——常见原因包括服务提供者未正确注册、缓存未刷新、环境配置冲突或自动发现机制失效，需系统性验证与清理。

Laravel Horizon 是 Laravel 官方提供的 Redis 队列监控仪表板，但其路由并非默认全局启用，而是依赖服务提供者注册、应用环境判断及门面（Gate）授权逻辑共同生效。即使 Horizon 进程运行正常（php artisan horizon:status 显示 “Horizon is running”），若路由未被加载，仍会返回 404。

✅ 关键检查点与解决方案

1. 确保 `HorizonServiceProvider` 已正确注册

Horizon 使用自动服务发现（Laravel ≥ 5.5），但若项目禁用了 PackageDiscovery 或手动修改过 config/app.php，需显式注册服务提供者：

// config/app.php
'providers' => [
    // ... 其他服务提供者
    LaravelHorizonHorizonServiceProvider::class,
],

⚠️ 注意：HorizonApplicationServiceProvider（如你自定义的 AppProvidersHorizonServiceProvider）是用于扩展授权逻辑的，不能替代 LaravelHorizonHorizonServiceProvider 的核心注册。二者需共存。

2. 清理所有缓存（不止路由缓存）

仅执行 php artisan route:clear 不足以解决此问题。Horizon 路由注册发生在服务提供者 boot() 阶段，受以下缓存影响：

php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear
# 若使用 OPCache（本地开发中较少见，但 Docker/VM 环境可能启用），也需重启 PHP 服务

3. 验证 `APP_ENV` 与路由启用逻辑

Horizon 默认仅在 local 和 testing 环境下自动注册 HTTP 路由（参见 LaravelHorizonHorizonApplicationServiceProvider::routes()）。请确认 .env 中：

APP_ENV=local

若误设为 production 或 staging，Horizon 将跳过路由注册——此时即使 Gate 授权逻辑存在，也无路可访。

Laravel Creem Agent

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

下载

4. 自定义 `HorizonServiceProvider` 的注意事项

你重写的 gate() 方法逻辑正确，但需确保：

该类已通过 config/app.php 中的 providers 数组注册（见第 1 点）；
不要移除或覆盖 HorizonApplicationServiceProvider::boot() 中的原始逻辑（如你当前 boot() 方法为空，没问题）；
Gate 名称必须严格为 'viewHorizon'（Laravel Horizon 内部硬编码校验，不可更改）。

5. 强制重新发布 Horizon 配置与资源（推荐）

执行以下命令确保前端资源与配置同步：

php artisan vendor:publish --provider="LaravelHorizonHorizonServiceProvider" --tag=public --force
php artisan vendor:publish --provider="LaravelHorizonHorizonServiceProvider" --tag=config --force

✅ 最终验证步骤

# 1. 确认环境
echo $(php artisan tinker -n -e "echo config('app.env');")

# 2. 查看 Horizon 相关路由（应有 /horizon 及子路径）
php artisan route:list | grep horizon

# 3. 检查服务提供者是否加载
php artisan tinker -n -e "dd(class_exists('Laravel\Horizon\HorizonServiceProvider'));"