Xdebug 安裝與配置完整指南（Windows / Linux）

Xdebug 是 PHP 最強大的除錯與效能分析擴展，提供堆疊追蹤、變數檢視、程式碼覆蓋率、效能剖析等功能。本文整理 Windows 與 Linux 環境的安裝步驟、關鍵參數設定、常見問題與進階用法。

Windows 環境安裝

1. 下載對應版本：至 官網 依 PHP 版本（php -v）、Thread Safety（phpinfo() 查看 Thread Safety）、VC 編譯版本下載 .dll。
2. 放置檔案：複製至 PHP ext 目錄（如 C:\php\ext\php_xdebug.dll）。
3. 修改 php.ini（確認路徑用 php --ini）：

[Xdebug]
zend_extension="C:/php/ext/php_xdebug.dll"
xdebug.mode=debug,develop,trace,profile
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log="C:/php/xdebug.log"
xdebug.idekey=VSCODE

注意：必須用 zend_extension 載入，不可用 extension。

Linux 環境安裝（編譯安裝）

wget https://xdebug.org/files/xdebug-3.3.1.tgz
tar -xzf xdebug-3.3.1.tgz
cd xdebug-3.3.1
phpize
./configure --with-php-config=/usr/local/php/bin/php-config
make && make install
# 輸出會提示 .so 路徑，加入 php.ini
echo 'zend_extension="/usr/local/php/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so"' >> /usr/local/php/lib/php.ini

關鍵參數詳解（Xdebug 3.x）

常見問題排查

• XDEBUG NOT LOADED AS ZEND EXTENSION：改用 zend_extension、確認路徑正確、重啟 PHP-FPM/Apache。
• 無法連線 IDE：檢查防火牆、xdebug.client_host、xdebug.client_port、IDE 監聽埠是否一致。
• 效能大幅下降：僅在需要時啟用 xdebug.mode=profile，或設 xdebug.start_with_request=trigger 配合 XDEBUG_TRIGGER Cookie 啟動。
• 與 OPcache 衝突：Xdebug 3.x 已修正大部分相容性問題，仍建議生產環境關閉 Xdebug。

進階用法：效能剖析

# 啟用剖析
xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug
xdebug.start_with_request=trigger

# 瀏覽器安裝 Xdebug Helper 擴充套件，設定 IDE Key 為 "PHPSTORM"
# 訪問頁面後，/tmp/xdebug 會產生 cachegrind.out.xxx
# 使用 KCacheGrind (Linux) / QCacheGrind (Win) / WebGrind (Web) 分析

整合 IDE 除錯

• VS Code：安裝 PHP Debug 擴充套件，launch.json 設定 "port": 9003。
• PhpStorm：Settings → PHP → Debug → DBGp proxy，啟用 "Start Listening"。

生產環境建議

嚴禁在生產環境啟用 Xdebug。若需線上排查，可短暫啟用 xdebug.mode=trace 配合 xdebug.start_with_request=trigger，完成後立即關閉並重啟 PHP。