Xdebug 是 PHP 除錯利器,配合 Zend Studio (或 PhpStorm、VS Code) 可進行斷點除錯、變數檢視、效能分析。本文詳細說明 Windows 環境下的安裝設定流程。
php -i 或 phpinfo() 確認關鍵資訊:
php_xdebug-版本-php版本-vc版本-ts/nts-x86/x64.dllphp_xdebug.dll 放入 PHP ext 目錄; php.ini 末尾新增
[xdebug]
zend_extension="php_xdebug.dll"
; 遠端除錯核心設定
xdebug.mode=debug,develop,trace
xdebug.start_with_request=yes
xdebug.client_host="127.0.0.1"
xdebug.client_port=9003
xdebug.discover_client_host=true
; 可選:效能分析
xdebug.profiler_enable=0
xdebug.profiler_output_dir="C:/tmp/xdebug_profiler"
xdebug.profiler_output_name="cachegrind.out.%p"
; 可選:追蹤
xdebug.trace_enable_trigger=1
xdebug.trace_output_dir="C:/tmp/xdebug_trace"
; 顯示本地變數
xdebug.show_local_vars=1
xdebug.show_error_trace=1
⚠️ Xdebug 3 版本參數大幅變更:xdebug.remote_* 已棄用,改用 xdebug.mode, xdebug.client_host/port, xdebug.start_with_request。
<?php
phpinfo();
// 搜尋 "xdebug" 應看到:
// xdebug support => enabled
// Version => 3.x.x
// IDE Key => (可自訂)
?>
或命令列:php -m | findstr xdebug
9003 (對應 xdebug.client_port)localhost (或 any)現代方式:瀏覽器擴充套件控制除啟動
設定 IDE Key 為 ZEND_STUDIO (或 PHPSTORM, VSCODE),點擊圖示切換為「Debug」狀態 (蟲子變綠/紅點),重新整理頁面即觸發除錯。
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
},
"xdebugSettings": {
"max_children": 100,
"max_data": -1,
"max_depth": 5
}
}
]
}
需安裝 PHP Debug 擴充套件。
| 問題 | 解決方案 |
|---|---|
| 無法連線 IDE | 檢查防火牆 9003 埠、xdebug.client_host、IDE 監聽埠 |
| 斷點不生效 | 路徑對應 pathMappings 錯誤、檔案未同步、opcache 干擾 |
| 效能極慢 | 關閉 profiler/trace、調整 max_children/data/depth |
| 多請求混亂 | xdebug.start_with_request=trigger 配合瀏覽器擴充套件 |
| Windows 路徑大小寫 | pathMappings 大小寫需一致 |
; 啟用分析器 (觸發模式)
xdebug.mode=profile
xdebug.profiler_enable_trigger=1
xdebug.profiler_output_dir="C:/xdebug_profiler"
; 分析工具: WinCacheGrind, QCacheGrind, PhpStorm 內建
; 函式呼叫追蹤
xdebug.mode=trace
xdebug.trace_enable_trigger=1
xdebug.trace_output_dir="C:/xdebug_trace"
xdebug.trace_format=1 ; 0=人類可讀, 1=電腦解析