在Herd环境下Laravel Reverb与Echo连接失败，如何排查调试？

问题描述 #

按默认步骤安装Laravel Reverb后，无法实现简单消息推送，前端控制台出现「websocket failed to connect」错误，本地使用Herd开发，已确认8080端口未被占用。

已配置的代码 #

事件类（TestEvent） #

class TestEvent implements ShouldBroadcastNow
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public string $message;

    public function __construct(string $message)
    {
        $this->message = $message;
    }

    public function broadcastOn()
    {
        return [new Channel('test-channel')];
    }
}

触发事件的Artisan命令 #

public function handle()
{
    TestEvent::dispatch('This is a test');
}

前端视图 #

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Echo?</title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
<h1>Echo?</h1>

<script>
    Echo.channel('test-channel')
        .listen('TestEvent', (e) => {
            console.log('TestEvent resp...');
            console.log(e);
        });
</script>
</body>
</html>

Echo配置（未修改） #

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

可能的问题与调试步骤 #

1. 核对环境变量配置 #

• 确认.env中VITE_REVERB_HOST为本地正确地址：Herd本地开发通常用localhost、127.0.0.1或自定义域名（如your-app.test），需与访问应用的域名一致
• 检查REVERB_PORT和VITE_REVERB_PORT均为8080（Reverb默认端口），避免前后端端口不匹配
• 本地开发关闭强制TLS：将VITE_REVERB_SCHEME设为http，确保forceTLS为false，否则会强制使用wss协议导致无SSL环境下连接失败

2. 确认Reverb服务正常启动 #

• 执行php artisan reverb:start，查看终端输出是否显示Reverb server started on 0.0.0.0:8080类成功信息，若有报错直接排查错误原因
• 用curl测试Reverb服务可用性：curl http://localhost:8080/apps/你的REVERB_APP_KEY/events，替换实际的REVERB_APP_KEY，若返回正常JSON响应则服务运行正常

3. 修正事件监听名称匹配问题 #

• Laravel默认广播事件会使用完整命名空间（如App\Events\TestEvent），前端仅监听TestEvent会无法匹配
• 解决方式二选一：
  • 在事件类中添加自定义事件名称：

    public function broadcastAs()
    {
        return 'TestEvent';
    }
    

  • 前端监听完整命名空间（注意转义反斜杠）：

    Echo.channel('test-channel')
        .listen('.App\\Events\\TestEvent', (e) => {
            console.log('TestEvent resp...');
            console.log(e);
        });
    

4. 排查WebSocket连接请求细节 #

• 打开浏览器开发者工具→Network→筛选「WS」，刷新页面查看WebSocket请求地址是否正确（如ws://localhost:8080/app/你的APP_KEY?xxx）
• 若地址错误，检查Vite是否正确加载环境变量：在前端控制台执行console.log(import.meta.env.VITE_REVERB_HOST)，确认输出与.env配置一致
• 若返回403错误，核对REVERB_APP_KEY与VITE_REVERB_APP_KEY完全相同，无拼写错误

5. 确认广播驱动配置 #

• 检查.env中BROADCAST_DRIVER=reverb，避免使用log或其他驱动导致事件无法推送到Reverb
• 执行php artisan config:clear清除配置缓存，确保新配置生效

6. Herd环境特殊检查 #

• 确认Herd的PHP版本≥8.2、Laravel版本≥11，满足Reverb的版本要求
• 若使用Herd的自定义域名，确保WebSocket请求的host与域名一致，无需额外Nginx转发（本地直接连接8080端口即可）

7. 日志排查 #

• 查看Laravel日志storage/logs/laravel.log，搜索「broadcast」关键词，排查事件广播是否有异常抛出
• 启动Reverb时添加详细日志：php artisan reverb:start --verbose，查看客户端连接记录、事件推送日志，定位是否有数据传输问题

内容的提问来源于stack exchange，提问作者TerryMatula