一、安裝 Xdebug
預編譯模組安裝 (Windows)
- 從 官網 下載對應 PHP 版本、TS/NTS、VC 版本的
php_xdebug.dll。
- 將 DLL 放入 PHP 擴展目錄（如
C:/php/ext/）。
- 編輯
php.ini，添加：
zend_extension_ts = "C:/php/ext/php_xdebug.dll"
; 非線程安全版請用 zend_extension = "..."
- 重啟 Apache/NGINX，執行
php -m 或 phpinfo() 確認 xdebug 已載入。
Linux 系統編譯安裝
cd /usr/local/src
wget https://xdebug.org/files/xdebug-3.2.0.tgz
tar -zxvf xdebug-3.2.0.tgz
cd xdebug-3.2.0
/usr/local/php/bin/phpize
./configure --enable-xdebug --with-php-config=/usr/local/php/bin/php-config
make && make install
編譯成功後，將生成的 xdebug.so 路徑加入 php.ini：
zend_extension = /usr/local/php/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so
二、核心功能配置參數詳解
1. 基礎特性
| 參數 | 類型 | 預設值 | 說明 |
|---|
| xdebug.default_enable | Boolean | On | 錯誤發生時自動顯示堆疊追蹤。建議開啟。 |
| xdebug.max_nesting_level | Integer | 100 | 限制函數遞歸深度，防止無限遞歸導致腳本中止。 |
2. 堆疊追蹤
| 參數 | 類型 | 預設值 | 說明 |
|---|
| xdebug.dump_globals | Boolean | 1 | 是否顯示超全局變數（$_SERVER, $_POST 等）內容。 |
| xdebug.dump_once | Boolean | 1 | 只在錯誤首次發生時輸出超全局變數，而非每次錯誤都輸出。 |
| xdebug.dump_undefined | Boolean | 0 | 是否輸出未定義的超全局變數值。 |
| xdebug.show_exception_trace | Integer | 0 | 捕獲到異常時仍強制顯示異常追蹤（設為 1）。 |
| xdebug.show_local_vars | Integer | 0 | 堆疊追蹤中顯示所有局部變數（含未初始化），資訊量大，預設關閉。 |
範例：xdebug.dump.SERVER = REQUEST_METHOD,REQUEST_URI,HTTP_USER_AGENT 將只輸出指定的 $_SERVER 索引。
3. 性能分析
| 參數 | 類型 | 預設值 | 說明 |
|---|
| xdebug.profiler_enable | Integer | 0 | 啟用性能分析，生成可被 KCacheGrind/QCacheGrind 讀取的快照文件。不可用 ini_set() 修改。 |
| xdebug.profiler_output_dir | String | /tmp | 分析文件輸出目錄，需 PHP 進程有寫入權限。不可用 ini_set() 修改。 |
| xdebug.profiler_output_name | String | cachegrind.out.%p | 輸出文件命名格式，支援 %p (PID), %r (請求數) 等佔位符。 |
| xdebug.profiler_append | Integer | 0 | 設為 1 時，新請求追加寫入同一文件而非覆蓋。 |
4. 遠程調試
| 參數 | 類型 | 預設值 | 說明 |
|---|
| xdebug.remote_enable | Boolean | 0 | 啟用遠程調試，嘗試連接 IDE 客戶端。 |
| xdebug.remote_autostart | Boolean | 0 | 忽略 GET/POST/COOKIE 觸發條件，每次請求都嘗試發起調試會話。 |
| xdebug.remote_host | String | localhost | IDE 客戶端所在主機 IP 或主機名。 |
| xdebug.remote_port | Integer | 9000 | 調試通訊端口，建議保持預設，避免衝突。 |
三、推薦生產/開發環境配置範例
[xdebug]
zend_extension = "/usr/local/php/lib/php/extensions/xdebug.so"
xdebug.default_enable = 1
xdebug.max_nesting_level = 256
; 開發環境建議開啟
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = "192.168.1.100"
xdebug.remote_port = 9000
; 性能分析按需開啟
xdebug.profiler_enable = 0
xdebug.profiler_output_dir = "/tmp/xdebug_profiler"
xdebug.profiler_output_name = "cachegrind.out.%H%R"
; 堆疊追蹤細節
xdebug.show_local_vars = 1
xdebug.dump_globals = 1
xdebug.dump.SERVER = REQUEST_METHOD,REQUEST_URI,HTTP_HOST
xdebug.dump.POST = *
四、常用分析工具
- WebGrind：PHP 寫的 Xdebug 分析文件 Web 界面，適合快速查看。
- KCacheGrind (Linux) / QCacheGrind (Windows)：圖形化分析調用圖、耗時統計。
- PhpStorm / VS Code：內建遠程調試支持，配合
xdebug.remote_autostart=1 即可零配置斷點調試。
五、注意事項
- Xdebug 3.x 版本配置鍵名有變更（如
xdebug.mode=debug,profile），升級時請閱讀遷移指南。
- 生產環境嚴禁開啟
profiler_enable 或 remote_autostart，會嚴重影響性能並暴露安全風險。
- 遠程調試時，確保服務器防火牆開放
9000 端口入站，或使用 SSH 隧道轉發。
