Xdebug 是 PHP 開發除錯的利器,搭配 PhpStorm 可實現斷點、變數檢視、堆疊追蹤等 IDE 級除錯體驗。本文詳細說明從下載、安裝、php.ini 設定到 IDE 與瀏覽器整合的完整流程。
phpinfo() 輸出貼上,自動推薦版本與設定.dll (Windows) 或 .so (Linux/macOS); Windows 範例
[XDEBUG]
zend_extension = "D:/php/ext/php_xdebug.dll"
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.idekey = "PHPSTORM"
xdebug.log = "D:/php/logs/xdebug.log"
xdebug.log_level = 7
注意:Xdebug 3 版本參數名稱變更(xdebug.remote_*→xdebug.client_*、xdebug.mode取代多個舊參數),請依安裝版本調整。
File → Settings → PHP → Debugxdebug.client_port)Settings → PHP → Servers 新增伺服器:
PHPSTORM(對應 php.ini xdebug.idekey)| 現象 | 可能原因 | 解決方式 |
|---|---|---|
| 斷點不生效 | Path Mapping 錯誤 | 檢查 Servers 設定的路徑對應 |
| 連線逾時 | Port 被佔用/防火牆 | 改用 9003、確認防火牆允許 |
| xdebug.log 顯示 "Could not connect to client" | client_host/port 錯誤 | 確認 PhpStorm 監聽中、IP 正確 |
| Docker 環境無法連線 | 容器內 localhost ≠ 宿主機 | 設定 xdebug.client_host=host.docker.internal |
在 php.ini 設定 xdebug.start_with_request = trigger,瀏覽器擴充套件或帶入 XDEBUG_SESSION=PHPSTORM 參數時才啟動除錯,避免影響效能。
完成上述設定後,你將擁有專業級的 PHP 除錯環境:斷點、單步執行、變數觀察、呼叫堆疊、評估運算式 一應俱全。建議搭配 xdebug.log 排查連線問題,並依專案需求調整 xdebug.mode(debug/trace/profile)。