為什麼升級 Xdebug 3？
- 效能大幅提升（預設關閉 profiling、tracing，按需啟用）。
- 配置簡化：
xdebug.mode 取代十幾個舊參數。
- 支援 PHP 8.0+、
match、Attributes、JIT 除錯。
- 雲端原生：
xdebug.client_host 自動偵測、xdebug.discover_client_host。
1. 安裝
# Linux (PECL)
pecl install xdebug
# 或 apt-get install php8.2-xdebug
# Docker (推薦)
# Dockerfile
RUN pecl install xdebug \
&& docker-php-ext-enable xdebug
2. 核心配置 php.ini / xdebug.ini
; === 必填 ===
zend_extension=xdebug.so
; 模式：debug, develop, trace, profile, coverage, gcstats
; 開發環境建議
xdebug.mode=debug,develop
; 連線目標（IDE 監聽地址）
xdebug.client_host=host.docker.internal ; Docker 內連宿主機
xdebug.client_port=9003 ; Xdebug 3 預設 9003 (舊版 9000)
; 自動啟動（瀏覽器擴充套件觸發更佳，見下）
xdebug.start_with_request=trigger ; trigger / yes / no
; 日誌除錯配置
xdebug.log=/var/log/xdebug.log
xdebug.log_level=7
模式詳解
| 模式 | 用途 | 效能影響 |
|---|
| debug | 斷點、變數檢查、堆疊 | 中（僅連線時） |
| develop | 變數顯示增強、錯誤頁面美化 | 低 |
| trace | 函數呼叫追蹤寫檔 | 高（大量 I/O） |
| profile | 效能分析 (Cachegrind 格式) | 高 |
| coverage | 程式碼覆蓋率 | 極高（僅測試時開啟） |
3. IDE 端配置
PhpStorm (內建零配置)
Preferences → PHP → Debug：Port 9003、勾選 Can accept external connections。Preferences → PHP → Servers：新增 Server，Host=你的域名/IP，Port=80/443，**勾選 Path mappings** 將專案根目錄映射到伺服器絕對路徑（如 /var/www/html）。- 工具列電話圖示 Start Listening for PHP Debug Connections 亮綠燈。
- 瀏覽器安裝 Xdebug Helper (Chrome/Firefox/Edge)，設定 IDE Key =
PHPSTORM，點擊除錯圖示變綠。
- 在程式碼打斷點，重新整理頁面 → PhpStorm 彈出除錯視窗。
VS Code (PHP Debug 擴充套件)
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
},
"hostname": "0.0.0.0",
"log": true
}
]
}
- 安裝
PHP Debug (xdebug.php-debug)。
- F5 啟動偵錯，狀態列顯示
Listening on 9003。
- 瀏覽器 Xdebug Helper 設定 IDE Key =
VSCODE。
4. 觸發除錯的三種方式
| 方式 | 適用場景 | 啟動參數 |
|---|
| 瀏覽器擴充套件 | Web 請求、API、AJAX | Cookie XDEBUG_SESSION=PHPSTORM |
| URL 參數 | 快臨時測試 | ?XDEBUG_SESSION_START=PHPSTORM |
| CLI 環境變數 | 命令列腳本、單元測試、Queue Worker | XDEBUG_SESSION=1 php artisan queue:work |
xdebug_break() | 程式碼硬性中斷 | 無需外部觸發 |
5. 進階：多伺服器 / Kubernetes / 遠端主機
- DBGp Proxy：
xdebug.client_host 指向 Proxy，Proxy 轉發至開發者 IDE。適合團隊共用測試環境。
- SSH Tunnel：
ssh -R 9003:localhost:9003 user@remote 將遠端 9003 映射回本機。
- K8s Sidecar：Sidecar 容器跑
dbgp-proxy，開發者連線至 Service。
6. 常見問題排查
| 現象 | 原因 | 解決 |
|---|
| 斷點不生效/跳過 | Path Mapping 錯誤 | 檢查 Server 設定的絕對路徑映射 |
| 連線超時 | 防火牆阻擋 9003 | 伺服器開放 9003 輸出；本機開放 9003 輸入 |
變數顯示 unavailable | OpCache 優化移除變數 | opcache.optimization_level=0 或關閉 OpCache（僅開發） |
| Docker 內無法連宿主機 | Linux 無 host.docker.internal | --add-host=host.docker.internal:host-gateway (Docker 20.04+) |
| 多請求只第一次停 | xdebug.start_with_request=yes 但 IDE 未持續監聽 | 改用 trigger + 瀏覽器擴充套件 |
7. 生產環境安全
- 嚴禁開啟 debug 模式：洩露堆疊、變數、環境變數，極大安全風險。
- 生產
xdebug.mode=off 或完全不載入擴展。
- 若需線上排查：
xdebug.mode=trace + 限制 IP + 短時間 + 立即關閉。
原文《利用Xdebug和Komodo調試PHP應用程序》重構，全面升級至 Xdebug 3 + PhpStorm/VS Code 現代工具鏈，補充 Docker/K8s/SSH 遠端場景與安全守則。
