PHPStorm + Xdebug 遠端斷點除錯完整設定指南

Xdebug 伺服器端設定 (php.ini)

重點配置 [XDebug] 區段，以下為生產可用範本：

[XDebug]
zend_extension="/usr/lib/php5/20090626+lfs/xdebug.so"
xdebug.default_enable = On
xdebug.collect_params = On
xdebug.remote_connect_back = On       ; 多開發者環境建議開啟，自動回連客戶端 IP
xdebug.remote_host = 192.168.59.104   ; 單一開發者時指定 IDE 所在機器 IP
xdebug.remote_port = 9900             ; 除錯通訊埠，需與 IDE 設定一致
xdebug.remote_enable = On
xdebug.remote_handler = dbgp
xdebug.remote_log = "/var/www/xdebug/xdebug.log"
xdebug.remote_req = req
xdebug.auto_trace = Off
xdebug.remote_autostart = On          ; 自動啟動除錯，無需瀏覽器觸發
xdebug.show_exception_trace = 0
xdebug.collect_vars = On
xdebug.collect_return = On
xdebug.collect_params = On
xdebug.var_display_max_depth = 15
xdebug.show_local_vars = 1
xdebug.dump_undefined = 1
xdebug.profiler_enable = 1
xdebug.profiler_output_dir = /var/www/xdebug

關鍵說明：

• remote_connect_back=On 適合多開發者共用測試伺服器，會忽略 remote_host。
• remote_autostart=On 讓每個請求自動嘗試連線 IDE，配合瀏覽器擴充功能（如 Xdebug Helper）最方便。
• 防火牆需開放 remote_port (預設 9000，此處 9900) 讓伺服器主動連回開發機。

PHPStorm 客戶端設定

1. Settings > PHP > Debug：
   設定 Debug port: 9900（對應 xdebug.remote_port）。
2. Settings > PHP > Servers：
   新增 Server，Host 填 Web 伺服器域名或 IP，Port 填 80/443。
   務必勾選 Use path mappings，將專案本地路徑對應到伺服器絕對路徑（如 /var/www/html），否則無法定位檔案導致除錯中斷。
3. Run > Edit Configurations：
   新增 PHP Web Application，選擇上方建立的 Server，Start URL 設為入口檔（如 /index.php）。

啟動除錯

在瀏覽器安裝 Xdebug Helper（Chrome/Firefox），設定 IDE Key 為 PHPSTORM，點擊圖標啟用「Debug」。或手動在 URL 附加參數：

https://your-site.com/index.php?XDEBUG_SESSION_START=PHPSTORM

PHPStorm 點擊「小蟲子」圖示（Listen for Debug Connections），重新整理頁面即進入除錯模式。

常見問題排查

• 無法連線：檢查防火牆、remote_port 一致性、remote_log 內容。
• 路徑映射錯誤：Servers 設定的 Path Mappings 必須精確到專案根目錄。
• 多專案共用伺服器：建議使用 remote_connect_back=On，各開發者各自開啟 Listen。