Xdebug 調試原理詳解

Xdebug 是一個功能強大的 PHP 調試擴展，它通過與 IDE（如 PHPStorm）建立通信隧道，實現代碼斷點調試、變量監控和性能分析等功能。下面從原理到配置進行詳細分析，并提供圖示幫助理解。

一、Xdebug 工作原理

1. 基本通信流程

瀏覽器請求 → Web服務器(NGINX/Apache) → PHP解釋器 → Xdebug擴展
                                                    ↓
                                               (調試端口:9000)
                                                    ↓
                                             PHPStorm調試器

• 步驟說明
  1. 瀏覽器發送請求到 Web 服務器
  2. Web 服務器將請求傳遞給 PHP 解釋器
  3. Xdebug 檢測到調試條件（如設置了斷點或啟用了調試會話）
  4. Xdebug 通過網絡連接到 PHPStorm（監聽 9000 端口）
  5. PHPStorm 控制執行流程并顯示變量狀態

2. Xdebug 2 vs Xdebug 3

二、Docker 環境中的網絡挑戰

在 Docker 環境中配置 Xdebug 需要解決容器與宿主機的網絡通信問題：

1. 容器與宿主機通信方式

┌─────────────────────────────────────────────────────────┐
│                    Windows 宿主機                        │
│  ┌───────────────┐    ┌──────────────────────────────┐   │
│  │   PHPStorm    │?───?│      Docker 守護進程         │   │
│  └───────────────┘    └───────────┬──────────────────┘   │
│                                   │                       │
│  ┌───────────────────────────┐    │    ┌───────────────┐  │
│  │                           │    │    │               │  │
│  │    Docker 網絡空間        │?───┼───?│  物理網卡     │  │
│  │                           │    │    │               │  │
│  │  ┌─────────────────────┐  │    │    └───────────────┘  │
│  │  │                     │  │    │                       │
│  │  │   PHP-FPM 容器      │  │    │                       │
│  │  │  (Xdebug 擴展)      │  │    │                       │
│  │  └─────────────────────┘  │    │                       │
│  └───────────────────────────┘    └───────────────────────┘
└─────────────────────────────────────────────────────────┘

2. 關鍵配置點

• Xdebug 需要知道宿主機（運行 PHPStorm 的機器）的 IP 地址
• Docker 提供了特殊域名 host.docker.internal 指向宿主機
• 需要開放調試端口（9000/9003）并確保防火墻允許通信

三、PHPStorm 調試配置詳解

1. 調試會話建立流程

plaintext

1. 用戶在 PHPStorm 中設置斷點
2. PHPStorm 啟動調試監聽（監聽 9000 端口）
3. 用戶通過瀏覽器訪問網站，并觸發調試會話
   - 方式一：在 URL 中添加 ?XDEBUG_SESSION_START=PHPSTORM
   - 方式二：使用瀏覽器擴展（如 Xdebug Helper）
4. Xdebug 捕獲請求，連接到 PHPStorm
5. PHPStorm 與 Xdebug 建立調試會話，控制代碼執行

2. 路徑映射原理

當使用 Docker 容器時，本地代碼和容器內代碼路徑可能不同，需要配置路徑映射：

本地路徑                     容器內路徑
┌────────────────┐         ┌────────────────┐
│ C:/project/app  │ 映射到 │ /var/www/app    │
└────────────────┘         └────────────────┘

PHPStorm 配置示例

服務器名稱: laradock
主機: localhost
端口: 80
調試器: Xdebug
路徑映射: C:/project/ → /var/www/

四、原理圖

五、常見問題排查思路

1. Xdebug 未加載

• 檢查 phpinfo() 中是否有 Xdebug 相關信息
• 確認 xdebug.ini 文件路徑正確且已被 PHP 加載
• 檢查 Docker 容器內 Xdebug 擴展文件是否存在（/usr/local/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so）

2. 調試會話無法建立

• 檢查 PHPStorm 是否正在監聽調試端口（電話圖標是否亮起）
• 確認防火墻未阻止 9000 端口通信
• 嘗試使用 telnet host.docker.internal 9000 測試連接

3. 斷點未命中

• 檢查路徑映射是否正確
• 確保代碼版本一致（本地與容器內）
• 嘗試在代碼開頭添加 xdebug_break() 強制斷點