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

為什麼需要除錯器？

許多 PHP 開發者習慣用 echo、var_dump()、print_r() 除錯，對簡單邏輯確實足夠。但隨著專案複雜度提升，這類「列印式除錯」存在明顯缺點：

• 需修改程式碼、部署後再移除，影響開發流程。
• 難以觀察呼叫堆疊、變數作用域變化、效能瓶頸。
• 多執行緒/非同步流程幾乎無法追蹤。

專業除錯器 (Debugger) 提供中斷點、單步執行、變數即時監看、呼叫堆疊檢視、程式碼覆蓋率分析 等功能，能大幅縮短問題定位時間。

什麼是 Xdebug？

Xdebug 是開源 PHP 除錯與分析擴充套件，支援：

• 步進除錯：配合 IDE (PhpStorm, VS Code, NetBeans) 實現中斷點、單步執行。
• 呼叫追蹤：自動記錄函式呼叫流程、參數、回傳值、執行時間。
• 效能分析：產生 CacheGrind 格式檔案，配合 QCacheGrind / WinCacheGrind 視覺化分析。
• 程式碼覆蓋率：配合 PHPUnit 產生測試覆蓋率報告。
• 變數顯示增強：改善 var_dump() 輸出格式、顏色、深度限制。

Windows 環境安裝配置

1. 下載對應 DLL

訪問 xdebug.org/download，根據 PHP 版本、Thread Safety (TS/Non-TS)、VC 編譯版本 下載正確的 php_xdebug.dll。
快速判斷：執行 php -i | findstr "Thread Safety"，顯示 enabled 為 TS，否則 Non-TS。

2. 配置 php.ini

; 1. 載入擴充套件 (必須用 zend_extension，不可用 extension)
zend_extension_ts="C:/php/ext/php_xdebug-3.2.0-8.1-vs16-x86_64.dll"

; 2. 基本除錯設定
xdebug.mode=debug,develop,trace,profile
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

; 3. 追蹤/分析輸出目錄 (需可寫入權限)
xdebug.trace_output_dir="C:/xdebug/trace"
xdebug.profiler_output_dir="C:/xdebug/profiler"

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

關鍵差異：Xdebug 3.x 參數大幅簡化，xdebug.mode 取代舊版多個開關；xdebug.start_with_request=yes 讓每個請求自動嘗試連接 IDE。

3. IDE 設定 (以 PhpStorm 為例)

1. File > Settings > PHP > Debug：確認 Debug port = 9003、勾選 Can accept external connections。
2. File > Settings > PHP > Servers：新增 Server，Host 為專案域名，勾選 Use path mappings 對應本地專案路徑。
3. 工具列點擊 Start Listening for PHP Debug Connections (電話圖示)。
4. 瀏覽器安裝 Xdebug Helper 擴充套件，設定 IDE Key = PHPSTORM，點擊除錯圖示啟用。

Linux 環境安裝配置 (以 Ubuntu/Debian 為例)

1. 套件管理器安裝 (推薦)

# PHP 8.1 範例
sudo apt update
sudo apt install php8.1-xdebug

# 自動產生 /etc/php/8.1/mods-available/xdebug.ini
# 需手動啟用並調整參數

2. 編譯安裝 (需特定版本)

# 安裝建置工具
sudo apt install php8.1-dev php-pear build-essential

# 下載原始碼編譯
wget https://xdebug.org/files/xdebug-3.2.0.tgz
tar -xzf xdebug-3.2.0.tgz
cd xdebug-3.2.0
phpize
./configure --enable-xdebug
make
sudo make install

# 輸出會提示 .so 路徑，例如 /usr/lib/php/20210902/xdebug.so

3. 配置 php.ini (Linux 通用)

; /etc/php/8.1/cli/conf.d/20-xdebug.ini 或 /etc/php/8.1/fpm/conf.d/20-xdebug.ini
zend_extension=xdebug.so

xdebug.mode=debug,develop,trace,profile
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.trace_output_dir=/tmp/xdebug/trace
xdebug.profiler_output_dir=/tmp/xdebug/profiler

; 遠端除錯 (Docker/VM) 需設定
; xdebug.client_host=host.docker.internal
; xdebug.discover_client_host=true

4. 重啟服務並驗證

# CLI 驗證
php -v
# 應顯示 "with Xdebug v3.2.0"

# FPM 重啟
sudo systemctl restart php8.1-fpm

# 檢查模組載入
php -m | grep xdebug

常見問題排查

生產環境安全建議

• 嚴禁在生產環境開啟除錯模式：會暴露堆疊追蹤、變數內容，嚴重洩露資訊且拖垮效能。
• 使用環境變數控制：xdebug.mode=。
• 僅在開發/測試環境安裝 Xdebug，生產環境編譯 PHP 時排除。