PHP 安裝 Xdebug 擴展完整指南

前言

Xdebug 是 PHP 開發中不可或缺的調試與分析工具，能提供堆疊追蹤、程式碼覆蓋率、效能分析等功能。本文將詳細說明如何在 Windows 環境下為 PHP 安裝並配置 Xdebug 擴展。

一、下載對應的 DLL 檔案

首先前往 Xdebug 官網，根據你的 PHP 版本、編譯器（VC9/VC11/VC14/VC15）、執行緒安全性（TS 或 NTS）下載對應的 php_xdebug.dll。可透過 phpinfo() 查看「Compiler」、「Architecture」、「Thread Safety」等資訊確認版本。

二、放置擴展檔案

將下載的 DLL 檔案複製到 PHP 安裝目錄下的 ext 資料夾中，例如 C:\php\ext\。

三、修改 php.ini 設定

打開 php.ini，在檔案末尾加入以下配置：

[Xdebug]
zend_extension="C:/php/ext/php_xdebug-3.2.0-7.4-vc15-nts.dll"
; 以下為常用參數，可根據需求調整
xdebug.mode=debug,develop,trace,profile
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host="127.0.0.1"
xdebug.log="C:/php/xdebug.log"
xdebug.trace_output_dir="C:/php/xdebug/trace"
xdebug.profiler_output_dir="C:/php/xdebug/profiler"

注意：

• 請確保 xdebug.trace_output_dir 與 xdebug.profiler_output_dir 指向的資料夾已存在，否則需手動建立。
• 若使用 PHP 8.1+ 及 Xdebug 3，配置參數已有變更，請參考官方文件調整。

四、重啟 Web 伺服器並驗證

重啟 Apache 或 Nginx（或透過 FastCGI 重啟 PHP-FPM），然後建立一個 test.php：

<?php
function testXdebug() {
    require_once('not_exist.php'); // 故意觸發錯誤以產生追蹤檔
}
testXdebug();
?>

在瀏覽器訪問該檔案，隨後檢查 xdebug.trace_output_dir 設定的資料夾是否生成 .xt 追蹤檔案。若有生成，代表安裝成功。

五、常見問題排查

• 未生成追蹤檔：確認資料夾權限、路徑拼寫、PHP 是否真正載入 Xdebug（查看 phpinfo() 中的 Xdebug 區塊）。
• IDE 無法連線：檢查 xdebug.client_port 與 IDE 設定一致（預設 9003），防火牆是否放行。
• 效能影響：開啟分析器會產生大量檔案，建議僅在需要時啟用 xdebug.mode=profile。

結語

完成上述步驟後，你已擁有強大的 PHP 調試環境。善用 Xdebug 的斷點、變數檢視、呼叫堆疊等功能，將大幅提升開發效率與程式碼品質。