您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

Xdebug 安裝與配置全攻略：從斷點調試到效能分析

編輯：PHP 綜合知識

為什麼需要 Xdebug？

Xdebug 是 PHP 最強大的調試與分析擴展，提供 斷點單步執行、堆疊追蹤、程式碼覆蓋率、效能分析 等功能，是現代 PHP 開發不可或缺的工具鏈核心。

Windows 下快速安裝

打開 phpinfo()，確認 PHP 版本 (如 7.4.33)、Thread Safety (TS/Non-TS)、Compiler (VC15 等) 與 Architecture (x86/x64)。
前往 Xdebug 官網下載頁，或使用 Xdebug Wizard 貼上 phpinfo() 輸出自動獲得正確 DLL 連結。
下載 php_xdebug---vc-x86_64.dll，重命名為 php_xdebug.dll 放入 ext 目錄。
編輯 php.ini，在最底部新增：

[Xdebug]
zend_extension="C:/php/ext/php_xdebug.dll"
; 必須用 zend_extension，不可用 extension=

; === 遠程調試 (IDE 連接) ===
xdebug.mode=debug,develop,trace,profile
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.idekey=VSCODE

; === 追蹤輸出 ===
xdebug.trace_output_dir="C:/php/trace"
xdebug.trace_format=0
xdebug.collect_params=4
xdebug.collect_return=1

; === 效能分析 ===
xdebug.profiler_output_dir="C:/php/profiler"
xdebug.profiler_output_name=cachegrind.out.%p

; === 開發輔助 ===
xdebug.var_display_max_depth=5
xdebug.var_display_max_children=256
xdebug.var_display_max_data=1024
xdebug.cli_color=1

建立 C:/php/trace 與 C:/php/profiler 目錄並給予寫入權限。
重啟 Apache / PHP-FPM，phpinfo() 應出現 Xdebug 區塊。

關鍵參數速查表

參數	預設	建議	用途
xdebug.mode	develop	debug,develop,trace,profile	啟用功能模組，逗號分隔
xdebug.client_port	9003	9003	DBGp 協議端口 (舊版 9000)
xdebug.start_with_request	default	yes / trigger	yes=每請求自動連 IDE，trigger=需觸發器
xdebug.trace_output_dir	/tmp	自定義可寫目錄	函數呼叫追蹤檔存放處
xdebug.profiler_enable	0	1 (或 trigger)	產生 CacheGrind 格式效能檔
xdebug.collect_params	0	4	追蹤時記錄函數參數完整內容
xdebug.collect_return	0	1	記錄函數返回值

IDE 整合範例：VS Code + PHP Debug

安裝 PHP Debug 擴展 (felixfbecker.php-debug)。
專案根目錄建立 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      },
      "ignore": ["**/vendor/**/*.php"]
    }
  ]
}

按 F5 啟動偵聽，瀏覽器安裝 Xdebug Helper 擴展並設定 IDE Key 為 VSCODE，即可在編輯器下斷點、觀察變數、單步執行。

效能分析實戰

產生的 cachegrind.out.xxx 可用 QCacheGrind (Windows) 或 KCacheGrind (Linux) 開啟，直觀查看：

每個函數的 自耗時 與 累積耗時
呼叫關係圖
熱點路徑

針對高耗時函數優化 SQL、減少迴圈、引入緩存，效果立竿見影。

常見問題排查

IDE 不斷點：檢查 xdebug.mode 包含 debug、端口一致、防火牆放行、pathMappings 路徑正確。
追蹤/分析檔未生成：目錄權限、磁碟空間、xdebug.start_with_request=trigger 時需傳入 XDEBUG_TRIGGER=trace 參數。
PHP 8.1+：Xdebug 3.x 已整合大量功能，舊版 2.x 參數 (如 xdebug.remote_enable) 已棄用，請參考官網升級指南。