Xdebug 實戰指南：PHP 應用除錯、效能分析與程式碼覆蓋率三大核心功能

為什麼需要 Xdebug？

傳統 var_dump/echo 除錯屬「事後鑑證」，Xdebug 提供「即時探查」：呼叫堆疊追蹤、變數檢查、條件中斷、效能剖析、覆蓋率統計。

安裝與基礎配置

# Ubuntu/Debian
sudo apt-get install php-xdebug
# 或 pecl
pecl install xdebug

# php.ini 關鍵設定
zend_extension=xdebug.so
xdebug.mode=debug,develop,trace,profile,coverage
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=VSCODE
xdebug.log=/var/log/xdebug.log

功能一：除錯

• 支援 DBGp 協議，整合 VS Code (PHP Debug)、PhpStorm、Eclipse PDT
• 斷點、單步執行、變數觀察、條件中斷、評估表達式
• 遠端除錯：xdebug.client_host 設為 IDE 所在 IP

功能二：呼叫追蹤

xdebug.mode=trace
xdebug.trace_output_dir=/tmp/xdebug
xdebug.trace_format=1  # 0=人類可讀, 1=電腦可解析
xdebug.collect_params=4  # 0-4 參數詳盡度
xdebug.collect_return=1
xdebug.collect_assignments=1

產生 trace.xt 檔案，可用 kcachegrind/qcachegrind 視覺化分析呼叫關係、耗時、記憶體。

功能三：效能分析

xdebug.mode=profile
xdebug.profiler_output_dir=/tmp/xdebug
xdebug.profiler_output_name=cachegrind.out.%p

產生 cachegrind.out.*，同樣用 KCacheGrind/QCacheGrind 分析：函數耗時、呼叫次數、記憶體分配、熱點路徑。

功能四：程式碼覆蓋率

xdebug.mode=coverage
# 配合 PHPUnit
phpunit --coverage-html ./report --coverage-xml ./coverage.xml

需 PHPUnit 設定 <coverage processUncoveredFiles="true">。

常見問題與優化

現代替代：PCOV (僅覆蓋率)

pecl install pcov
# php.ini
extension=pcov.so
pcov.enabled=1
pcov.directory=/var/www/html
pcov.exclude="~vendor~"

PCOV 專注覆蓋率，效能優於 Xdebug 10 倍以上，適合 CI 流程。