PHP 遠程調試 Xdebug 完整配置指南（IDE 整合與最佳實踐）

PHP 遠程調試 Xdebug 完整配置指南（IDE 整合與最佳實踐）

Xdebug 是 PHP 開發者必備的調試擴展，支援斷點、單步執行、變量檢查、堆疊追蹤、覆蓋率分析等功能。本文詳細講解如何在遠程/虛擬機/容器環境中配置 Xdebug 3，並整合 PhpStorm/IntelliJ IDEA 實現高效遠程調試。

架構原理：DBGp 協議

• IDE (Client)：監聽 TCP 端口（預設 9003），接收調試連接
• PHP + Xdebug (Server)：代碼執行時主動連接 IDE，發送調試信息
• 通訊流向：PHP → IDE（反向連接），故 IDE 需可被 PHP 訪問（公網 IP/端口映射/SSH 隧道）

環境拓撲範例

步驟一：伺服器安裝 Xdebug 3

# Ubuntu/Debian
apt-get update && apt-get install -y php-xdebug

# CentOS/RHEL/Rocky/AlmaLinux
yum install -y php-pecl-xdebug

# 或通過 PECL 安裝最新版
pecl install xdebug-3.3.1

# 驗證安裝
php -m | grep xdebug
php -v
# 應顯示：with Xdebug v3.3.1, Copyright (c) 2002-2023, by Derick Rethans

步驟二：配置 php.ini (Xdebug 3 語法)

編輯 /etc/php/8.1/fpm/conf.d/20-xdebug.ini 或 /usr/local/php/etc/php.ini：

[xdebug]
; 基礎啟用
zend_extension=xdebug.so
xdebug.mode=debug,develop,trace,profile

; 遠程調試核心配置
xdebug.client_host=192.168.1.100      ; IDE 所在 IP（開發機）
xdebug.client_port=9003               ; IDE 監聽端口（Xdebug 3 預設 9003）
xdebug.start_with_request=yes         ; 自動發起調試連接（trigger 可配合瀏覽器擴展）
xdebug.discover_client_host=false     ; 不自動檢測 $_SERVER['HTTP_X_FORWARDED_FOR']
xdebug.log=/var/log/xdebug.log        ; 調試日誌（排查連接問題關鍵）
xdebug.log_level=7                    ; 日誌詳盡度 0-10

; 性能與輸出
xdebug.max_nesting_level=256
xdebug.var_display_max_depth=5
xdebug.var_display_max_children=256
xdebug.var_display_max_data=1024

; IDE Key（瀏覽器擴展觸發用）
xdebug.idekey=PHPSTORM

關鍵參數解析

重啟 PHP-FPM 生效：systemctl restart php8.1-fpm 或 service php-fpm restart

步驟三：PhpStorm/IntelliJ IDEA 配置

1. 設置 PHP 解釋器與路徑映射

1. Settings/Preferences → PHP → CLI Interpreter → 配置遠程解釋器（SSH/Vagrant/Docker/WSL）
2. Settings → PHP → Servers → 新增 Server：
   • Name: Remote Server
   • Host: 192.168.1.200 (或域名)
   • Port: 80/443
   • Debugger: Xdebug
   • ✅ Use path mappings：本地路徑 /home/user/project ↔ 伺服器路徑 /var/www/app

2. 配置調試入口

1. Run → Edit Configurations → + → PHP Remote Debug
2. Name: Remote Debug
3. Server: 選擇上方建立的 Remote Server
4. IDE Key: PHPSTORM (與 php.ini 一致)
5. Apply/OK

3. 啟動監聽並設置斷點

• 工具欄點擊 📞 Start Listening for PHP Debug Connections（電話圖標變綠）
• 在代碼行號左側點擊設置紅點斷點
• 瀏覽器訪問目標頁面（或用 Xdebug Helper 擴展觸發）
• PhpStorm 彈出調試面板，變量面板顯示當前作用域所有變量

步驟四：常見連接問題排查

進階場景：SSH 隧道反向代理（開發機無公網 IP）

若開發機在內網/NAT 後，伺服器無法直接連接，建立 SSH 反向隧道：

# 在開發機執行（需保持終端開啟）
ssh -R 9003:localhost:9003 user@192.168.1.200 -N -T

# 伺服器 php.ini 配置
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
# 此時 Xdebug 連接伺服器本地 9003，經 SSH 隧道轉發到開發機 9003

進階場景：Docker 容器調試

# docker-compose.yml
services:
  php:
    build: .
    volumes:
      - ./src:/var/www/html
    environment:
      XDEBUG_MODE: debug
      XDEBUG_CLIENT_HOST: host.docker.internal  # Docker Desktop 專用
      XDEBUG_CLIENT_PORT: 9003
      XDEBUG_START_WITH_REQUEST: yes
      XDEBUG_IDEKEY: PHPSTORM
    # Linux 原生 Docker 需額外配置：
    # extra_hosts:
    #   - "host.docker.internal:host-gateway"

瀏覽器觸發調試：Xdebug Helper

• Chrome: Xdebug Helper
• Firefox: Xdebug Helper
• 設置 IDE Key: PHPSTORM，點擊圖標切換 Debug 狀態（綠色蟲子）
• 配合 xdebug.start_with_request=trigger，僅在需要時啟動調試，避免每請求都連接 IDE 影響性能

效能優化建議

• 按需啟用：生產環境 禁用 Xdebug；開發環境用 trigger 模式
• 關閉分析器：xdebug.mode=debug 僅開啟調試，profile/trace 極大拖慢性能
• 限制變量顯示：xdebug.var_display_max_depth=3 減少傳輸數據量
• 使用預編譯：OPcache + Xdebug 共存需注意載入順序，zend_extension=opcache.so 在 zend_extension=xdebug.so 之前

總結檢查清單

1. ✅ 伺服器安裝 Xdebug 3，php -m | grep xdebug 可見
2. ✅ php.ini 配置 client_host、client_port、start_with_request、idekey
3. ✅ 重啟 PHP-FPM，xdebug.log 記錄連接嘗試
4. ✅ PhpStorm 配置 Server + Path Mappings 精確對應
5. ✅ PhpStorm 建立 PHP Remote Debug 配置，IDE Key 一致
6. ✅ 點擊 📞 開始監聽，設置斷點，瀏覽器觸發（Xdebug Helper）
7. ✅ 調試面板彈出，變量可檢查，單步執行正常

完成上述配置，即可享受如同本地開發般的遠程斷點調試體驗，大幅提升排查複雜業務邏輯、異常堆疊、性能瓶頸的效率。