您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

PhpStorm + Xdebug 3 遠端除錯完整設定指南 (Windows/Linux/macOS)

編輯：PHP 相關知識

Xdebug 是 PHP 除錯利器，配合 PhpStorm 可實現斷點、變數檢視、堆疊追蹤。本文針對 Xdebug 3.x (目前主流) 提供從下載、php.ini 設定、IDE 設定、瀏覽器擴充套件到實戰除錯的完整步驟。

步驟 1：取得正確的 Xdebug 擴充檔

執行 php -i 或建立 phpinfo.php 取得完整 PHP 資訊。
前往 Xdebug Wizard，貼上 php -i 輸出，點擊「Analyse」。
Wizard 會告訴你：具體下載連結 (如 php_xdebug-3.2.1-7.4-vc15-x86_64.dll) 與 完整 php.ini 設定範例。
下載對應檔案放入 PHP ext 目錄 (如 C:\php\ext 或 /usr/lib/php/extensions/)。

步驟 2：設定 php.ini (關鍵)

; ---- Xdebug 3.x 設定範例 ----
[Xdebug]
zend_extension = "C:\php\ext\php_xdebug.dll"  ; Windows 絕對路徑
; zend_extension = "/usr/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so" ; Linux/macOS

; 除錯模式啟用
xdebug.mode = debug,develop,trace

; 連線目標 (PhpStorm 預設監聽 9003)
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003

; IDE Key (需與 PhpStorm / 瀏覽器擴充一致)
xdebug.idekey = "PHPSTORM"

; 可選：啟動時自動連線 (不想每次都要觸發)
; xdebug.start_with_request = yes

; 可選：記錄除錯日誌 (排查連線問題)
xdebug.log = "C:\php\xdebug.log"
xdebug.log_level = 7

重要變更：Xdebug 3 棄用 xdebug.remote_* 系列參數，改用 xdebug.mode、xdebug.client_host/port、xdebug.idekey。舊版教學常誤導設定。

步驟 3：PhpStorm 設定

File → Settings → PHP → Debug：確認 Debug port = 9003，勾選「Can accept external connections」。
PHP → Servers：新增 Server
- Name: MyProject
- Host: localhost (或實際域名)
- Port: 80 / 443
- Debugger: Xdebug
- Use path mappings：對應專案本地路徑 ↔ 伺服器絕對路徑 (如 /var/www/html ←→ C:\Projects\MyProject)
Run → Start Listening for PHP Debug Connections (工具列電話圖示變綠)。

步驟 4：瀏覽器擴充套件 (觸發除錯)

點擊擴充圖示選擇 Debug (綠色蟲子)，後續請求會攜帶 XDEBUG_SESSION=PHPSTORM Cookie。

步驟 5：實戰除錯流程

在 PhpStorm 程式碼左側點擊行號設定斷點 (紅點)。
確認 Start Listening 開啟。
瀏覽器開啟專案頁面，Xdebug Helper 切換為 Debug。
重新整理頁面 → PhpStorm 彈出 Incoming Connection 對話框 → 選擇對應 Server → Accept。
程式執行停在斷點，可在 Debug 工具窗 檢視變數、呼叫堆疊、評估表達式。

常見問題排查

Q: 點擊 Listen 後無反應 / 彈不出 Incoming Connection？: 1. 檢查 xdebug.log 是否有 I: Connecting to configured address/port。
2. 確認防火牆允許 9003 通訊 (Windows: 允許 php.exe 通訊)。
3. Server Name Indication (SNI) 環境需在 Server 設定正確 Host。
4. Docker/VM 環境：xdebug.client_host=host.docker.internal (Mac/Win) 或宿主機實際 IP。
Q: 斷點顯示「不在此檔案」/ 變數無法顯示？: Path Mapping 未正確設定。在 Servers 設定中，本地專案根目錄必須對應到伺服器端 DocumentRoot 絕對路徑。
Q: 除錯極慢 / 頁面載入超時？: 關閉 xdebug.mode=profile；調高 max_execution_time；確保 xdebug.log 不在大量寫入。
Q: CLI 腳本除錯？: 執行 php -dxdebug.mode=debug -dxdebug.client_port=9003 script.php，或在 PhpStorm 建立 PHP Script Run Configuration。