PhpStorm + Xdebug 零門檻調試教程：從擴展安裝到斷點斷點調試全流程

環境基線

步驟一：安裝對應版本 Xdebug 擴展

1. 進入 Xdebug Wizard，貼上 php -i 輸出，獲取專屬下載鏈接與安裝指令。
2. Windows：下載 php_xdebug-3.2.2-8.2-vs16-x86_64.dll 放入 ext/ 目錄。
   Linux/macOS：pecl install xdebug 或包管理器安裝。

步驟二：php.ini 精準配置（Xdebug 3.x 風格）

[Xdebug]
zend_extension="D:/php/ext/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.idekey = PHPSTORM
xdebug.log = "D:/php/logs/xdebug.log"
xdebug.log_level = 7

關鍵點：
• xdebug.mode=debug 啟用調試器（3.x 合併了 remote_enable 等舊參數）。
• start_with_request=yes 讓每個請求自動嘗試連接 IDE，無需瀏覽器插件觸發。
• client_port=9003 為 3.x 預設端口，避開 9000（常被 php-fpm 佔用）。
• xdebug.log 連接失敗時的救命稻草，務必開啟。

步驟三：驗證擴展載入

php -m | grep xdebug
php -v | grep Xdebug

或瀏覽 phpinfo() 搜尋 "Xdebug"，應顯示版本號與配置表。

步驟四：PhpStorm 內建伺服器與除錯配置

4.1 設定 PHP 直譯器與伺服器

File → Settings → PHP → CLI Interpreter 選擇本地 PHP 執行檔。
Settings → PHP → Servers 新增：

• Name: Local
• Host: localhost (或你的虛擬主機域名如 myapp.test)
• Port: 80/443
• Debugger: Xdebug
• Use path mappings：專案根目錄 ↔ 伺服器文檔根目錄（如 /var/www/html）

4.2 除錯連接埠對齊

Settings → PHP → Debug → Xdebug：
Debug port: 9003（與 xdebug.client_port 一致）
Can accept external connections：勾選

4.3 建立 Run/Debug Configuration

Run → Edit Configurations → + → PHP Web Page：

• Name: Debug Local
• Server: 選 Local
• Start URL: /index.php 或具體路由
• Browser: Chrome（建議安裝 Xdebug Helper 擴展）

步驟五：啟動調試會話

1. 在代碼行號左側點擊設置斷點（紅點）。
2. 點擊工具欄 電話聽筒圖標 (Start Listening for PHP Debug Connections) 變綠。
3. 點擊 甲蟲圖標 (Debug 'Debug Local') 或 Shift+F9。
4. 瀏覽器自動打開 Start URL，請求到達 PHP，Xdebug 連接 PhpStorm，IDE 彈出「Incoming Connection」對話框，確認路徑映射後點 Accept。
5. 代碼自動停在斷點，變量面板顯示當前作用域所有變量值。