Windows 下 Xdebug 3 完整安裝配置指南：從 DLL 下載到 PhpStorm 遠程調試

版本對應表 (關鍵！)

原則：PHP 版本、VC 編譯器、TS/NTS **三者必須完全匹配**。用 php -i | findstr "Compiler\|Thread Safety" 確認。

安裝步驟

1. 下載對應 DLL

• 官網：xdebug.org/download
• 向導：xdebug.org/wizard (貼上 php -i 輸出自動推薦)
• 放置：C:\php\ext\php_xdebug.dll (或你的 PHP ext 目錄)

2. 配置 php.ini (Xdebug 3 新語法)

; 必須用 zend_extension 載入，不能用 extension=
zend_extension = "C:\php\ext\php_xdebug.dll"

[xdebug]
; 模式：開發調試用 develop,debug,coverage,gcstats,profile,trace
xdebug.mode = develop,debug,profile

; 客戶端 (IDE) 連接配置
xdebug.client_host = "127.0.0.1"
xdebug.client_port = 9003          ; Xdebug 3 默認 9003 (舊版 9000)
xdebug.start_with_request = yes    ; 自動啟動調試 (trigger 可配合瀏覽器插件)
xdebug.discover_client_host = true ; 嘗試自動檢測客戶端 IP (Docker/WSL 有用)

; 日誌 (排查連接問題必開)
xdebug.log = "C:\php\xdebug.log"
xdebug.log_level = 7

; 性能分析輸出
xdebug.output_dir = "C:\php\xdebug_profiler"
xdebug.profiler_output_name = "cachegrind.out.%p.%R"

; 代碼覆蓋率
xdebug.coverage_enable = 1

; 變量顯示深度/長度
xdebug.var_display_max_depth = 5
xdebug.var_display_max_children = 256
xdebug.var_display_max_data = 1024

; IDE Key (PhpStorm 默認 PHPSTORM)
xdebug.idekey = "PHPSTORM"

3. 衝突處理：Zend Optimizer / OPcache

Xdebug **必須**在 OPcache **之前**載入，且不能與 Zend Optimizer 共存。

; 正確順序
zend_extension = "C:\php\ext\php_xdebug.dll"
zend_extension = "C:\php\ext\php_opcache.dll"  ; 如果啟用 OPcache

; 註釋掉 Zend Optimizer
; [Zend]
; zend_extension_manager.optimizer_ts = "..."
; zend_extension_ts = "..."

4. 重啟 Web 服務器並驗證

# CLI 驗證
php -v
# 應顯示: with Xdebug v3.2.0, Copyright (c) 2002-2022, by Derick Rethans

# 或瀏覽 phpinfo() 頁面搜索 xdebug

PhpStorm 配置 (最常用 IDE)

1. 設置 PHP 解釋器

Settings → PHP → CLI Interpreter → 選擇你的 php.exe → 確認 Xdebug 版本顯示正確

2. 配置 Debug 端口

Settings → PHP → Debug → Xdebug → Debug port: 9003 (與 xdebug.client_port 一致)

3. 配置 Server 映射 (關鍵：本地路徑 ↔ 服務器路徑)

Settings → PHP → Servers → 新增：

• Name: localhost
• Host: localhost
• Port: 80 (或你的 Nginx/Apache 端口)
• Debugger: Xdebug
• Use path mappings：勾選
• File/Directory: C:\project\myapp → Absolute path on server: /var/www/html (或同樣的 Windows 路徑)

4. 瀏覽器調試流程

1. PhpStorm 右上角電話圖標「Start Listening for PHP Debug Connections」變綠
2. 安裝瀏覽器擴展：Xdebug Helper (Chrome) / Firefox 同名插件
3. 擴展設置 IDE Key = PHPSTORM
4. 點擊擴展圖標選 Debug
5. 瀏覽器訪問項目 URL，PhpStorm 彈出調試界面，斷點生效

常見問題排查

VS Code 配置 (launch.json)

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "ignore": ["**/vendor/**/*.php"]
        }
    ]
}

生產環境安全建議

• 禁用 Xdebug：xdebug.mode = off 或註釋 zend_extension
• 防止信息洩露：xdebug.mode 不包含 develop (會在錯誤頁顯示變量)
• 編譯緩存：OPcache 生產環境必開，Xdebug 關閉

總結

Xdebug 3 配置核心在於：**版本三要素匹配 → zend_extension 載入順序 → client_port=9003 → IDE 路徑映射 → 瀏覽器插件觸發**。掌握這條主線，配合 xdebug.log 排查 90% 問題。開發環境常駐 develop,debug，生產環境徹底禁用。