# 安裝編譯工具鏈
apt-get install php-dev autoconf automake libtool # Debian/Ubuntu
yum install php-devel gcc make # CentOS/RHEL
# PECL 安裝最新穩定版
pecl install xdebug
# 或指定版本 (對應 PHP 版本)
# pecl install xdebug-3.2.2 # PHP 8.0-8.2
# pecl install xdebug-2.9.8 # PHP 7.2-7.4
php_xdebug.dll。php/ext/ 目錄。php.ini 載入 (見下)。php -m | grep xdebug
php -v # 應顯示 "with Xdebug v3.x.x, Copyright (c) 2002-2023, by Derick Rethans"
[Xdebug]
; 必須使用 zend_extension 載入 (非 extension)
zend_extension = "C:/php/ext/php_xdebug.dll" ; Windows 絕對路徑
zend_extension = "/usr/lib/php/20210902/xdebug.so" ; Linux 典型路徑
; 模式:開發預設開啟多項功能
xdebug.mode = develop,debug,profile,trace
; 開發模式預設值
xdebug.start_with_request = yes ; 自動啟動 (debug/trace/profile)
xdebug.output_dir = "/tmp/xdebug" ; 輸出目錄 (需可寫)
xdebug.log = "/tmp/xdebug/xdebug.log" ; 除錯日誌
xdebug.log_level = 7 ; 0-10,7 為詳細
; 遠端除錯 (PhpStorm/VS Code)
xdebug.client_host = "127.0.0.1" ; IDE 所在 IP
xdebug.client_port = 9003 ; Xdebug 3 預設 9003 (舊版 9000)
xdebug.discover_client_host = true ; 自動偵測客戶端 IP (Docker/遠端適用)
; 堆疊追蹤
xdebug.trace_format = 1 ; 0=人類可讀, 1=電腦解析, 2=HTML
xdebug.trace_options = 1 ; 1=追加模式
; 效能分析
xdebug.profiler_output_name = "cachegrind.out.%p.%t"
xdebug.profiler_append = 0
; 變數顯示深度/長度限制
xdebug.var_display_max_depth = 5
xdebug.var_display_max_children = 256
xdebug.var_display_max_data = 1024
; 防無限遞歸
xdebug.max_nesting_level = 256
trace..xt 檔案,記錄每個函數呼叫、參數、返回值、耗時、記憶體。trace-analyzer、qcachegrind (支援 trace 格式)、自寫解析腳本。cachegrind.out.* 檔案。Incl. (含子呼叫總耗時)、Self (自身耗時)、Calls (呼叫次數)。xdebug.mode=coverage 配合 PHPUnit 生成 clover.xml、crap4j.xml、HTML 報告。| 現象 | 原因與解決 |
|---|---|
| IDE 顯示「Waiting for Xdebug connection」 | 檢查 xdebug.client_port 與 IDE 設定一致 (3.x=9003, 2.x=9000);檢查防火牆;Docker 環境設 xdebug.discover_client_host=1 或指定 client_host=host.docker.internal。 |
| 「Could not connect to client」 | Xdebug 3 需 xdebug.mode=debug 且 start_with_request=yes/trigger;檢查 xdebug.log 連線嘗試記錄。 |
| 效能極差/記憶體暴漲 | 關閉不需的模式:xdebug.mode=debug (僅除錯);生產環境嚴禁開啟 Xdebug。 |
| VS Code Breakpoint 未命中 | 確認 launch.json "port": 9003、"pathMappings" 正確映射專案根目錄至容器/遠端路徑。 |
Xdebug 是開發/測試環境的利器,生產環境請改用輕量級 APM 工具。