Laravel 11 使用 Pusher Channels 實現廣播功能完整教程

在現代的網頁應用中，實時通信已成為提升用戶體驗的關鍵元素。Laravel 提供了強大的廣播系統，可以輕鬆地將服務器端的事件實時推送到客戶端。本文將詳細介紹如何在 Laravel 11 中使用 Pusher Channels 來實現廣播功能。

前言

Laravel 的廣播系統允許您在應用程序中輕鬆地實現實時功能，如聊天、通知等。Pusher 是一個托管的 WebSocket 平台，可以與 Laravel 無縫整合，使實時通信更加簡單。

環境準備

Laravel 版本：11.x
PHP 版本：需要滿足 Laravel 11 的要求
Node.js 和 NPM：用於安裝前端依賴
Pusher 帳戶：需要在 Pusher 官方網站註冊一個帳戶

安裝與配置

安裝 Laravel Broadcasting

首先，按照官方文檔的指示，安裝 Laravel 的廣播組件：


php artisan install:broadcasting

安裝 Pusher PHP SDK

接下來，安裝 Pusher 的 PHP 服務器端 SDK：


composer require pusher/pusher-php-server

配置 .env 檔案

在 .env 檔案中，設置廣播驅動為 pusher：


BROADCAST_CONNECTION=pusher

接著，添加 Pusher 的相關配置：














PUSHER_APP_ID=your-pusher-app-id
PUSHER_APP_KEY=your-pusher-key
PUSHER_APP_SECRET=your-pusher-secret
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME=https
PUSHER_APP_CLUSTER=ap3

VITE_APP_NAME="${APP_NAME}"
VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
VITE_PUSHER_HOST="${PUSHER_HOST}"
VITE_PUSHER_PORT="${PUSHER_PORT}"
VITE_PUSHER_SCHEME="${PUSHER_SCHEME}"
VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

請確保將 your-pusher-app-id、your-pusher-key 和 your-pusher-secret 替換為您在 Pusher 服務中獲取的實際值。

注意：PUSHER_APP_CLUSTER 的值需要與您在 Pusher 控制台中選擇的集群相匹配。例如，如果您選擇了東京（ap3），則需要設置為 ap3。

安裝客戶端套件

安裝 Laravel Echo 和 Pusher JS

在客戶端，我們需要安裝 laravel-echo 和 pusher-js：


npm install --save-dev laravel-echo pusher-js

配置客戶端 JavaScript

創建一個新的文件 resources/js/echo.js，並添加以下內容：














import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

// 開啟 Pusher 日誌（開發環境）
Pusher.logToConsole = true;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    forceTLS: true,
});

在 resources/js/bootstrap.js 中導入剛才的 echo.js：


import './echo';

創建事件並廣播

創建廣播事件

使用 Artisan 命令創建一個新的事件：


php artisan make:event MyEvent

在生成的 app/Events/MyEvent.php 中，確保該事件實現了 ShouldBroadcast 接口：






























<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class MyEvent implements ShouldBroadcast
{
    use Dispatchable, SerializesModels;

    public $message;

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

    public function broadcastOn()
    {
        return new Channel('my-channel');
    }

    public function broadcastAs()
    {
        return 'my-event';
    }
}

觸發事件

在路由中添加一個測試路由，用於觸發事件：






use App\Events\MyEvent;

Route::get('/test-broadcast', function () {
    event(new MyEvent('這是一條測試廣播訊息'));
    return '事件已觸發';
});

客戶端接收廣播

在您的前端應用中，添加以下代碼來監聽廣播事件。假設您在一個 Vue 組件中：






mounted() {
    Echo.channel('my-channel')
        .listen('my-event', (e) => {
            console.log('收到廣播訊息：', e);
        });
}

現在，當您訪問 /test-broadcast 路由時，客戶端應該能夠在控制台中看到接收到的廣播消息。

透過Pusher Debug console測試

可以透過Pusher提供的Debug console來查看Log，也可以直接傳送事件，已進行測試

常見問題與解決方案

/broadcasting/auth 404 (Not Found)
問題：使用私有頻道時，出現 /broadcasting/auth 404 (Not Found) 錯誤。

解決方案：確保在 bootstrap/app.php 中有包含 channels.php：








return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__ . '/../routes/web.php',
        api: __DIR__ . '/../routes/api.php',
        commands: __DIR__ . '/../routes/console.php',
        channels: __DIR__ .  '/../routes/channels.php', // 確保添加了此行
        health: '/up',
    )

此外，在 routes/channels.php 中定義您的私有頻道授權規則。

Did you forget to specify the cluster?
問題：收到錯誤信息，提示是否忘記指定集群。

解決方案：檢查客戶端和服務器端的集群設置是否一致。

在 echo.js 中：






window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    forceTLS: true,
});

在 .env 中：


PUSHER_APP_CLUSTER=ap3

確保 VITE_PUSHER_APP_CLUSTER 和 PUSHER_APP_CLUSTER 的值一致。如果更改了 .env，請清理配置快取並重新編譯資源：


php artisan config:cache
npm run build

無法接收到廣播事件
問題：事件已觸發，但客戶端沒有收到。

解決方案：

確認事件類實現了 ShouldBroadcast 接口。
檢查事件的 broadcastOn 方法，確保頻道名稱一致。
在客戶端，確認訂閱的頻道名稱和事件名稱正確。
檢查 Pusher 儀表板，查看事件是否成功發送。

結論

通過以上步驟，我們成功地在 Laravel 11 中使用 Pusher Channels 實現了廣播功能。這使得我們的應用可以實時地向客戶端推送消息，提升用戶體驗。

在實際項目中，您可以進一步探索私有頻道、存在頻道以及與身份驗證系統的集成。此外，Laravel Broadcasting 還支持其他廣播驅動，如 Redis、Socket.IO 等，您可以根據需要選擇最適合的方案。

希望本教程對您有所幫助！