在 ServBay 中搭建與運行 Workerman 應用

概述

本文件旨在引導 ServBay 使用者如何在 macOS 本地開發環境下，利用 ServBay 已整合的 PHP 與 Composer，快速搭建並執行基於 Workerman 的高效能非同步網路應用。Workerman 是一款功能強大的 PHP 函式庫，適合用來構建需要高併發處理的各類網路服務，如 Web 伺服器、即時通訊伺服器、遊戲伺服器等。ServBay 提供開箱即用的開發平台，大幅簡化 Workerman 的環境配置流程。

什麼是 Workerman？

Workerman 是一套完全以 PHP 撰寫的開源高效能非同步網路通訊框架。它基於 EventLoop 事件循環機制，實現非同步與非阻塞 I/O，能夠有效處理大量併發連線。與傳統 PHP Web 開發模式（如 Apache/Nginx + PHP-FPM）不同，Workerman 通常以常駐記憶體的方式運行，持續監聽指定埠口，直接處理網路連接與資料，因而省去了傳統模式中每次請求處理完即銷毀進程所帶來的額外消耗，顯著提升系統性能與吞吐量。

透過 Workerman，開發者可以輕鬆搭建：

高效能 HTTP 伺服器，甚至可取代 Apache/Nginx 處理簡單的靜態或動態請求。
即時 WebSocket 伺服器，適用於聊天室、即時資料推播等應用。
各種自定義協定的 TCP/UDP 伺服器。
命令列工具、排程任務、微服務等。

Workerman 的核心特色與優勢

高效能：核心基於事件驅動與非同步非阻塞 I/O，能夠處理海量併發連線，提供傑出效能。
多協定支援：內建支援 HTTP、WebSocket、TCP、UDP 等主流網路協定，也開放接口供開發者擴充自定義協定。
上手簡易：API 直觀簡潔，大幅降低非同步網路程式設計的難度，PHP 工程師亦能輕鬆快速入門。
彈性擴充：支援多進程架構，善用多核心 CPU 以水平擴展與分攤負載，方便整合 Composer 套件與現有 PHP 函式庫。
無縫融入 PHP 生態：做為一個 PHP 函式庫，能與 PHP 廣闊的生態系統緊密結合，並藉由 Composer 管理依賴。
守護進程模式：可作為守護進程（Daemon）於背景穩定運行，適合生產環境部署，保證服務長時間可用。

Workerman 為 PHP 開發者開啟了打造高效能、即時、高併發網路應用的大門。

使用 ServBay 搭建 Workerman 開發環境

ServBay 是專為 Web 開發者打造的本地開發環境工具，整合了 PHP、Node.js、Python、Go、Java 等主流程式語言執行時，以及 Caddy、Nginx、Apache、MySQL、PostgreSQL、MongoDB、Redis、Memcached 等常見資料庫與伺服器軟體。ServBay 的最大優勢在於其「開箱即用」的特性，且已內建並設定好 Composer 環境，大大便利用戶在 ServBay 中快速搭建與運行 Workerman 專案。

本指南將透過幾個基礎範例，示範如何在 ServBay 環境下快速搭建與執行 Workerman 應用，包括一個簡單的 HTTP 伺服器、一個 WebSocket 伺服器及一個 TCP 伺服器。

TIP

為方便管理及統一規範，ServBay 建議將所有本地網站專案檔案存放於 /Applications/ServBay/www 目錄下。本文所有專案路徑皆以此路徑為範例。

前置條件

開始前，請確保已具備下列條件：

已安裝並啟動 ServBay：請前往 ServBay 官方網站下載並安裝最新版 ServBay。
已啟用 ServBay 中的 PHP：至 ServBay 控制面板，確認欲使用之 PHP 版本已啟動。Workerman 需 PHP 5.4 或更新，建議使用 PHP 7.x 或 8.x 以獲最佳效能。
具有基本的 PHP 編程與終端操作知識：需理解 PHP 基本語法及如何於終端執行命令列指令。

安裝 Workerman

1. 確認 Composer 可用

ServBay 已內建 Composer，無須額外安裝。請確認 ServBay 環境已啟動，且已啟用你計劃使用的 PHP 版本。ServBay 會自動配置相應 PHP 版本的 Composer。你可於 ServBay 終端、或（若 PHP 與 Composer 已加至系統 PATH）外部終端，進入 ServBay 的 PHP 環境運行 Composer。

於終端輸入以下指令確認 Composer 是否可用：

bash

composer -v

若 Composer 在 ServBay PHP 環境中安裝無誤，則會顯示 Composer 版本資訊。若未找到命令，請檢查 ServBay 是否已啟動及 PHP 版本是否已啟用。

2. 建立專案目錄

前往 ServBay 推薦的網站根目錄，建立新專案資料夾後進入該目錄：

bash

cd /Applications/ServBay/www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

這裡我們建立名為 servbay-workerman-demo 的資料夾，用來存放 Workerman 專案檔案。

3. 透過 Composer 安裝 Workerman

於專案目錄 (/Applications/ServBay/www/servbay-workerman-demo) 執行 Composer 安裝 Workerman 套件。Composer 會自動處理相依套件：

bash

composer require workerman/workerman

Composer 會自動下載 Workerman 與其所有依賴至本目錄下的 vendor 資料夾中。

撰寫 Workerman HTTP 伺服器程式

HTTP 伺服器是 Workerman 最常見的應用場景之一，適用於構建高效能 Web 應用或 API 服務。

於專案目錄下建立一個名為 http_server.php（或你喜歡的名字，如 server.php）的檔案，並加入以下 PHP 程式碼：

php

<?php
// 載入 Composer 的自動載入檔，以便引入 Workerman 類別
require __DIR__ . '/vendor/autoload.php';

// 使用 Workerman 的 Worker 類
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// 建立一個 Worker 實例，指定監聽協定與位址
// 'http://0.0.0.0:8080' 代表建立一個 HTTP 伺服器，監聽所有網卡（0.0.0.0）的 8080 埠口
// 0.0.0.0 可讓本機或區網其它設備皆可連線；8080 為監聽的埠號。
$http_worker = new Worker('http://0.0.0.0:8080');

// 設定 Worker 啟動進程數
// 此設定為 4，代表啟動 4 個獨立 PHP 進程處理請求，可依實際 CPU 核心數調整
$http_worker->count = 4;

// 定義接收到客戶端訊息（HTTP 請求）時的處理邏輯
// $connection 為當前連線物件，可用來回應客戶端
// $request 是當前請求物件，包含請求 (URL, Headers, Body 等) 詳細資訊
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // 回傳簡單字串作為 HTTP 回應
    // Workerman 會自動處理 HTTP header 等細節
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// 啟動所有 Worker 實例
// 這為 Workerman 主迴圈，啟動後 Worker 進程會監聽埠口並處理事件
Worker::runAll();

程式解說：

require __DIR__ . '/vendor/autoload.php';：載入 Composer 自動載入檔，方便使用 Workerman 各類別（如 Worker, Request, Response 等）。
use Workerman\...;：引入所需類別。
new Worker('http://0.0.0.0:8080')：新建 Workerman 實例。參數為監聽協定（http）與位址（0.0.0.0:8080）。
$http_worker->count = 4;：設定 Workerman 啟動進程數。進程越多，可用多核心提升併發能力。
$http_worker->onMessage = function(TcpConnection $connection, Request $request) { ... };：定義收到完整 HTTP 請求時的回調函式。$connection 可回應客戶端，$request 包含客戶端傳送之請求資訊。Response 用於構建標準 HTTP 回應。
Worker::runAll();：啟動 Workerman 事件迴圈，所有已定義的 Worker 開始監聽處理連線。

運行 Workerman HTTP 伺服器

於專案目錄 (/Applications/ServBay/www/servbay-workerman-demo) 開啟終端，運行下列命令啟動 HTTP 伺服器：

bash

php http_server.php start

運行模式說明：

前台模式 (Foreground)： 執行 php http_server.php start 時，Workerman 於前台運作，終端會輸出運作資訊與日誌。可用 Ctrl+C 停止。此模式適合開發與除錯。
守護進程模式 (Daemon)： 生產環境一般需在背景以守護進程運行 Workerman。可加 -d 參數：
bash
```
php http_server.php start -d
```
1
Workerman 將於背景執行，輸出內容導至日誌檔中（預設於 Workerman 目錄下或指定路徑）。

進程管理：

Workerman 提供下列便捷進程管理命令：

啟動： php http_server.php start（前台），php http_server.php start -d（背景）
停止： php http_server.php stop（處理完現有請求後優雅關閉）
重啟： php http_server.php restart（先停再開）
平滑重啟 (Reload)： php http_server.php reload（常用於程式碼更新，會逐一重啟子進程不中斷服務，需留意 onWorkerStart 等生命週期函式的寫法）
檢查狀態： php http_server.php status（檢視 Workerman 進程運作狀態、記憶體占用、連線數等）

啟動後，請開啟瀏覽器前往 http://localhost:8080 或 http://127.0.0.1:8080。畫面將顯示 Hello ServBay Workerman HTTP Server!。

使用 Workerman 創建 WebSocket 伺服器

WebSocket 協定允許客戶端與伺服器之間建立持久雙向連線，非常適合即時應用，例如線上聊天室、即時行情推播、遊戲等。Workerman 對 WebSocket 支援完善。

建立 WebSocket 伺服器程式

於專案目錄下新建一個 websocket_server.php 檔案，並加入下列程式碼：

php

<?php
require __DIR__ . '/vendor/autoload.php';

use Workerman\Worker;
use Workerman\Connection\TcpConnection;

// 建立 WebSocket 伺服器實例，監聽 8081 埠
// 'websocket://0.0.0.0:8081' 代表建立 WebSocket 伺服器
// Workerman 會自動處理 WebSocket 握手等細節
$ws_worker = new Worker('websocket://0.0.0.0:8081');

// 啟動 4 個進程來處理連線
$ws_worker->count = 4;

// 定義連線建立時的處理
// 有新客戶端連入時觸發
$ws_worker->onConnect = function(TcpConnection $connection) {
    echo "New WebSocket connection from " . $connection->getRemoteIp() . "\n";
};

// 定義接收訊息時的處理
// 當伺服器收到 WebSocket 訊息時觸發
// $data 為已解碼之客戶端訊息內容
$ws_worker->onMessage = function(TcpConnection $connection, $data) {
    echo "Received message: " . $data . "\n";
    // 回送收到的訊息給客戶端
    // $connection->send() 會自動以 WebSocket 格式發送
    $connection->send('ServBay Workerman received: ' . $data);
};

// 定義連線關閉時的處理
// 客戶端斷線時觸發
$ws_worker->onClose = function(TcpConnection $connection) {
    echo "WebSocket Connection closed\n";
};

// 定義錯誤發生時的處理（選用）
$ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
    echo "Error: $code - $msg\n";
};


// 啟動所有 Worker 實例
Worker::runAll();

啟動 WebSocket 伺服器

在專案目錄下，於終端執行下面命令啟動 WebSocket 伺服器：

bash

php websocket_server.php start

可加上 -d 參數背景運行。啟動後，你可使用 WebSocket 客戶端工具連線 ws://localhost:8081。

例如，可在瀏覽器開發者工具 Console 以 JavaScript 測試：

javascript

var ws = new WebSocket("ws://localhost:8081");

ws.onopen = function(event) {
  console.log("WebSocket connection opened");
  ws.send("Hello from Browser!"); // 發送訊息
};

ws.onmessage = function(event) {
  console.log("Message from server:", event.data); // 接收訊息
};

ws.onclose = function(event) {
  if (event.wasClean) {
    console.log("WebSocket connection closed cleanly, code=" + event.code + " reason=" + event.reason);
  } else {
    console.error("WebSocket connection died");
  }
};

ws.onerror = function(error) {
  console.error("WebSocket error:", error);
};

// 關閉連線（選用）
// ws.close();

連線成功後，終端會顯示連線資訊，發送訊息後也會看到訊息日誌，且瀏覽器收到伺服器回傳內容。

使用 Workerman 建立 TCP 伺服器

Workerman 也可打造一般 TCP 伺服器，處理所有需基於 TCP 協定的應用層資料，特別適用於開發遊戲伺服器、物聯網平台、自定義通訊服務等。

建立 TCP 伺服器程式

於專案目錄下新增 tcp_server.php 並寫入下列程式期碼：

php

<?php
require __DIR__ . '/vendor/autoload.php';

use Workerman\Worker;
use Workerman\Connection\TcpConnection;

// 建立 TCP 伺服器實例，監聽 8082 埠口
// 'tcp://0.0.0.0:8082' 代表建立 TCP 伺服器
// Workerman 預設使用 Text 協定（行尾符 '\n'），也可指定/
$tcp_worker = new Worker('tcp://0.0.0.0:8082');

// 啟動 4 個進程處理連線
$tcp_worker->count = 4;

// 定義連線建立後的處理
$tcp_worker->onConnect = function(TcpConnection $connection) {
    echo "New TCP connection from " . $connection->getRemoteIp() . "\n";
    // 連線建立時發送歡迎訊息
    $connection->send("Welcome to ServBay Workerman TCP Server!\n");
};

// 定義收到訊息時的處理
// $data 為客戶端發來的 TCP 原始資料（經協定解析後的內容）
$tcp_worker->onMessage = function(TcpConnection $connection, $data) {
    echo "Received data: " . $data;
    // 回送收到的資料給客戶端
    $connection->send('ServBay Workerman received: ' . $data);
};

// 定義連線關閉時的處理
$tcp_worker->onClose = function(TcpConnection $connection) {
    echo "TCP Connection closed\n";
};

// 啟動所有 Worker 實例
Worker::runAll();

啟動 TCP 伺服器
在專案目錄下運行以下命令啟動 TCP 伺服器：
bash
```
php tcp_server.php start
```
1
同樣可加 -d 於背景運行。啟動後，您可透過 TCP 客戶端連 localhost:8082。
例：在 macOS/Linux 終端開啟另一視窗，執行 telnet 或 nc：
bash
```
# 使用 telnet
telnet localhost 8082

# 或用 nc (netcat)
nc localhost 8082
```
1
2
3
4
5
聯接成功後，會看到伺服器送來的歡迎訊息。隨意輸入文字（預設使用 Text 協定，需敲回車），伺服器將回送您發的內容。

注意事項

埠口佔用：請確認 Workerman 監聽的埠號（示例：8080、8081、8082）未被 macOS 系統或 ServBay 其它程式占用。如有衝突，Workerman 將啟動失敗。可用 lsof -i :埠號 查詢佔用狀況。
防火牆：macOS 內建防火牆可能阻止外部設備存取這些埠口。在本地開發一般沒影響，但若需從區網其它裝置訪問 Workerman 服務，請檢查與適當設定 macOS 防火牆。
與 ServBay Web 伺服器之關係：Workerman 運行於自定義埠號，與 ServBay 套件所啟的 Caddy 或 Nginx 為獨立進程與服務。Workerman 常直接處理連線，不必透過 Caddy/Nginx 代理（除非特別設定反向代理需求）。Workerman 更適合長連線或高併發非同步情境（如 WebSocket），ServBay 內建的 Caddy/Nginx 則多用於傳統短連線 HTTP 請求。
PHP 版本：請確認 ServBay 用於運行 Workerman 的 PHP 版本符合其最低需求。ServBay 本身支援多版本 PHP，能依專案需要於控制面板切換使用。
擴充套件依賴：Workerman 依賴某些 PHP 擴充功能以獲最佳效能，如 event 擴充（若已裝、將優先使用，效能更佳）、posix、pcntl（支援多進程）。ServBay 預設已啟用多數常見擴充，如遇問題請自行於 ServBay 控制面板檢查。
日誌檔管理：守護進程模式下 Workerman 輸出將導至日誌檔。請定期檢查日誌掌握應用狀況及潛在錯誤。

常見問題解答 (FAQ)

Q: 如何停止 Workerman 伺服器？
- A: 若伺服器於前台運行（執行 start），直接 Ctrl+C 停止即可。若以守護進程方式（start -d）啟動，請於專案目錄執行 php your_server_file.php stop 停止。
Q: 為何 Workerman 伺服器啟動失敗？
- A: 最常見原因為指定埠號已被占用。請檢查終端所顯示錯誤信息，通常會提示埠號佔用。可換未佔用埠號，或關閉已佔用此埠之程序，亦可用 lsof -i :埠號 查正在佔用該埠之進程。
Q: ServBay 的 Caddy/Nginx 與 Workerman 有何不同？我該用哪個？
- A: ServBay 的 Caddy/Nginx 為傳統 Web 伺服器，主要處理標準 HTTP/HTTPS 請求，常搭配 PHP-FPM，每個請求處理完 PHP 進程會結束。Workerman 是 PHP 非同步網路框架，既能自建 HTTP 伺服器，也可處理 WebSocket、TCP 協定等，會常駐記憶體更適合高併發、長連線或即時性應用。依需求選擇：傳統網站/RESTful API 請用 Caddy/Nginx；即時聊天、遊戲後端、物聯網等用 Workerman。亦可綜合使用，例如用 Caddy/Nginx 反向代理指定流量至 Workerman。
Q: 我可以在 ServBay 同時執行多個 Workerman 應用嗎？
- A: 可以。每一個 Workerman 應用都需於獨立 PHP 進程中運行，且聆聽不同埠口。只需為每個應用撰寫個別啟動腳本，在各自終端（或以背景執行）啟動即可，確保埠號不重複。

總結

透過本指南，你已學會如何於 ServBay 這個高效率本地開發環境中，快速建立並運行 Workerman 專案。Workerman 憑藉高效能與非同步特性，賦予 PHP 開發者打造新一代網路應用的強大能力，配合 ServBay 所提供立即可用的 Composer 與 PHP 執行環境，讓你專注業務開發，省去大量環境配置的繁瑣。不論是建立高效能 Web 服務、抑或開發即時互動的 WebSocket 應用，ServBay 都是你善用 Workerman 的理想本地開發夥伴。期望本文能協助你順利啟航 Workerman 的探索之路！

在 ServBay 中搭建與運行 Workerman 應用 ​

概述 ​

什麼是 Workerman？ ​

Workerman 的核心特色與優勢 ​

使用 ServBay 搭建 Workerman 開發環境 ​

前置條件 ​

安裝 Workerman ​

1. 確認 Composer 可用 ​

2. 建立專案目錄 ​

3. 透過 Composer 安裝 Workerman ​

撰寫 Workerman HTTP 伺服器程式 ​

運行 Workerman HTTP 伺服器 ​

使用 Workerman 創建 WebSocket 伺服器 ​

使用 Workerman 建立 TCP 伺服器 ​

注意事項 ​

常見問題解答 (FAQ) ​

總結 ​

在 ServBay 中搭建與運行 Workerman 應用

概述

什麼是 Workerman？

Workerman 的核心特色與優勢

使用 ServBay 搭建 Workerman 開發環境

前置條件

安裝 Workerman

1. 確認 Composer 可用

2. 建立專案目錄

3. 透過 Composer 安裝 Workerman

撰寫 Workerman HTTP 伺服器程式

運行 Workerman HTTP 伺服器

使用 Workerman 創建 WebSocket 伺服器

使用 Workerman 建立 TCP 伺服器

注意事項

常見問題解答 (FAQ)

總結