使用 XDebug 調試 PHP 專案

XDebug 是 PHP 開發中功能強大的調試、效能分析與程式碼覆蓋率檢測工具。在 ServBay 本地開發環境中整合並使用 XDebug，能夠顯著提升 PHP 專案開發效率與程式碼品質。透過 XDebug，開發者可以設置斷點、檢查變數值、追蹤函式呼叫堆疊、分析效能瓶頸等，大幅提升問題定位與解決的效率。

XDebug 簡介

XDebug 是專為 PHP 設計的擴充套件，提供了強大的調試與分析能力。它支援遠端調試（通常透過 DBGp 通訊協定）、斷點設置、單步執行、檢查變數值、追蹤函式呼叫堆疊、分析腳本效能 (Profiling)，以及產生程式碼覆蓋率報告 (Coverage)。藉由 XDebug，開發者可以深入掌握程式執行流程與狀態，從而更有效率地解決問題。

XDebug 支援多種工作模式，其中最常用的是 debug 模式，主要用於互動式斷點調試。

在 ServBay 啟用並配置 XDebug

ServBay 預先為所有支援的 PHP 版本安裝好了 XDebug 擴充，您無需手動下載或編譯。

啟用 XDebug 模組： 開啟 ServBay 應用介面。導航至 語言 - PHP，選擇您需要啟用 XDebug 的 PHP 版本。在擴充中找到 xdebug 模組，確保其狀態為「已啟用」。如果未啟用，請點擊開啟。啟用後可能需要重啟 PHP-FPM 服務（ServBay 通常會自動完成這步）。
配置您的 IDE： 在您常用的整合開發環境 (IDE)，如 PHPStorm 或 VS Code 中，設置 XDebug 連線。這通常包含設置監聽的埠號（需與 ServBay 介面中的 XDebug 設定一致），以及可能的遠端路徑對應（如果您的專案路徑與伺服器端不同，但在 ServBay 本地一般不用特別設置）。
更多 IDE 設定細節
關於如何在特定 IDE（如 PHPStorm、VS Code 等）中配置 XDebug 的詳細步驟，請參考該 IDE 官方文件，或參閱如何啟用 ServBay 內建的 Xdebug 模組這篇文章。

實戰範例：在 ServBay 調試 PHP 專案

我們將通過一個簡單的範例專案，演示在 ServBay 中如何使用 XDebug 進行調試。

1. 設立 ServBay 網站

首先，在 ServBay 中建立一個新網站來部署我們的範例專案：

在 ServBay 網站根目錄 /Applications/ServBay/www/ 下建立一個新的專案資料夾，例如 servbay-xdebug-app。
打開 ServBay 介面，導航至「網站」區塊。
點擊新增網站，設定網站根目錄為 /Applications/ServBay/www/servbay-xdebug-app。
指定一個本地域名，例如 servbay-xdebug-app.servbay.demo。
選擇您欲使用的 PHP 版本，並確保該版本已如上步驟啟用且配置好 XDebug。
儲存並套用更動。ServBay 將自動配置 Caddy/Nginx 並更新 hosts 檔（或透過 ServBay 的 DNS 服務）。

2. 範例專案結構與程式碼

於目錄 /Applications/ServBay/www/servbay-xdebug-app/ 下建立如下檔案結構：

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

src/Calculator.php 檔案內容如下：

php

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // 在這一行設置斷點
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

index.php 檔案內容如下：

php

<?php
// 假設您使用 Composer，這裡載入自動加載器
// 若未使用 Composer，請依實際情況調整載入方式
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Debugging Example:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Sum: " . $sum . "\n";
echo "Difference: " . $difference . "\n";

echo "Done.\n";
?>

注意： 上述 require __DIR__ . '/vendor/autoload.php'; 假設您有使用 Composer。如果僅做簡單測試，可移除此行，並將 use App\Calculator; 替換為 require __DIR__ . '/src/Calculator.php';。

3. 設定斷點

在您的 IDE（如 PHPStorm）中打開 /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php 檔案，於 add 方法的 return $a + $b; 行號旁點擊，設置斷點。

4. 啟動調試會話

在 IDE 內啟動監聽 XDebug 連線，於 PHPStorm 中通常為點擊上方工具欄的「開始監聽 PHP 調試連接」按鈕（一個電話聽筒或小蟲子圖示）。
在瀏覽器中訪問您的 ServBay 網站 index.php 檔案：https://servbay-xdebug-app.servbay.demo/index.php。
若您設定 xdebug.start_with_request 為 trigger，請確認已透過瀏覽器外掛或手動方式添加 XDebug 觸發器（如訪問 https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1）。

5. 調試流程

瀏覽器訪問 index.php 並觸發 XDebug 後，XDebug 會自動連至 IDE，並在您設置的斷點處暫停執行。
IDE 會自動進入調試介面，顯示程式碼停在 Calculator.php 檔案中 add 方法的斷點行。

6. 檢查變數值

在 IDE 的調試視窗，您可以看到目前執行的程式碼行、呼叫堆疊 (Call Stack)、變數值 (Variables) 等資訊。
在「Variables」面板中，可檢查目前作用域內各變數值。例如，您應會看到 $a 為 5，$b 為 3。

7. 逐步執行

使用 IDE 的逐步執行按鈕（常有 Step Over (F8)、Step Into (F7)、Step Out (Shift+F8) 等）。
- Step Over：執行目前這行，如該行是呼叫函式則不進入，而直接跳至下一行。
- Step Into：執行當前這行，若是函式呼叫即進入該函式內部第一行。
- Step Out：執行完當前函式剩餘程式，然後跳回呼叫處。
透過逐步執行，您可以逐行觀察程式流程及變數變化。

8. 繼續執行

點擊 IDE 內的「繼續執行（Resume Program）」按鈕（通常為綠色播放圖示或 F9），程式會繼續執行至下一個斷點或直至結束。

9. 查看輸出

程式執行結束後，可於瀏覽器（或以 CLI 調試時於終端機）看到輸出結果。本範例應輸出：
text
```
Debugging Example:
Sum: 8
Difference: 2
Done.
```
1
2
3
4

注意事項

防火牆： 請確保作業系統的防火牆未擋住 IDE 監聽的埠號（預設為 9003）。
埠號衝突： 確認 XDebug 設定的埠沒有被其他應用程式佔用。
效能影響： 當 xdebug.mode=debug 且 xdebug.start_with_request=yes 時，所有 PHP 請求都會嘗試啟動調試，會影響網站效能。如暫不需調試，建議停用 XDebug 模組或將 xdebug.start_with_request 改為 trigger。
CLI 腳本調試： XDebug 亦可調試 PHP CLI 腳本。您需於命令列設環境變數或特殊參數觸發調試，詳細方法請參考 XDebug 官網文件。
IDE 版本與設定： 不同 IDE 版本及設定畫面略有差異，建議參考官方說明文件完成設定。

常見問題解答 (FAQ)

Q: 我的 IDE 無法連接到 XDebug，怎麼辦？

A: 請依下列項目逐一檢查：

確認 ServBay 中對應 PHP 版本的 XDebug 模組已經啟用。
檢查 php.ini 內 xdebug.mode、xdebug.client_host、xdebug.client_port 設定正確，且與 IDE 監聽的設定一致。
若您使用 xdebug.start_with_request = trigger，請確認觸發器（GET/POST 參數、Cookie、Header）已正確加上。
確保您的作業系統防火牆允許 XDebug 埠號通訊。
確認您的 IDE 正在監聽目標埠。

Q: 啟用 XDebug 後，網站變慢的原因是？

A: 很可能因將 xdebug.start_with_request 設為 yes。此模式會使每個 PHP 請求都啟動偵錯，帶來顯著效能負擔。建議設為 trigger，僅需要調試時再手動觸發。

Q: 可以用 XDebug 調試 AJAX 請求嗎？

A: 可以。AJAX 請求和一般 HTTP 請求調試方式類似，只要確保 AJAX 請求也帶上 XDebug 觸發器（如設置 Cookie 或 Header）。

Q: 除 PHPStorm 外，ServBay 的 XDebug 能否支援 VS Code 或其他 IDE？

A: 能。ServBay 整合的 XDebug 是標準 PHP 擴充，遵從 DBGp 協定，可支援任何這類 IDE 或編輯器，例如 VS Code（搭配 PHP Debug 擴充）、NetBeans、Eclipse 等。設定方法相似，關鍵在於設定正確的監聽埠號。

結論

利用 ServBay 整合的 XDebug，開發者可以在本地環境高效調試 PHP 專案。熟悉斷點、變數檢查、逐步執行等核心調試方法，將大幅提升問題定位與解決能力，提升程式碼品質。結合 ServBay 強大便利的環境管理，XDebug 將成為您 PHP 開發工作流程中的重要利器。立即在 ServBay 使用 XDebug，開啟更順暢、更高效的 PHP 開發新體驗吧！

使用 XDebug 調試 PHP 專案 ​

XDebug 簡介 ​

在 ServBay 啟用並配置 XDebug ​

實戰範例：在 ServBay 調試 PHP 專案 ​

1. 設立 ServBay 網站 ​

2. 範例專案結構與程式碼 ​

3. 設定斷點 ​

4. 啟動調試會話 ​

5. 調試流程 ​

6. 檢查變數值 ​

7. 逐步執行 ​

8. 繼續執行 ​

9. 查看輸出 ​

注意事項 ​

常見問題解答 (FAQ) ​

結論 ​