萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

Xdebug 完整配置指南:安裝、堆疊追蹤、效能分析與遠端除錯

一、安裝 Xdebug

Linux/macOS (PECL 安裝,推薦)

# 安裝編譯工具鏈
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

Windows

  1. 至 xdebug.org/download 下載對應 PHP 版本、TS/Non-TS、VC 編譯版的 php_xdebug.dll。
  2. 放入 php/ext/ 目錄。
  3. 修改 php.ini 載入 (見下)。

驗證安裝

php -m | grep xdebug
php -v  # 應顯示 "with Xdebug v3.x.x, Copyright (c) 2002-2023, by Derick Rethans"

二、php.ini 核心配置 (Xdebug 3.x 語法)

[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

三、功能模組詳解

1. 除錯模式

  • 配合 IDE (PhpStorm/VS Code + PHP Debug) 設置斷點、單步執行、變數觀察、評估表達式。
  • 瀏覽器擴充套件 Xdebug Helper (Chrome/Firefox) 一鍵觸發除錯 Cookie。

2. 堆疊追蹤

  • 生成 trace..xt 檔案,記錄每個函數呼叫、參數、返回值、耗時、記憶體。
  • 工具分析:trace-analyzer、qcachegrind (支援 trace 格式)、自寫解析腳本。
  • 適用場景:梳理陌生代碼呼叫鏈、定位「誰呼叫了這個函數」。

3. 效能分析

  • 生成 cachegrind.out.* 檔案。
  • 視覺化工具:KCacheGrind (Linux/KDE)、QCacheGrind (跨平台 Qt)、WinCacheGrind (Windows)、Webgrind (PHP Web 介面)。
  • 關鍵指標:Incl. (含子呼叫總耗時)、Self (自身耗時)、Calls (呼叫次數)。

4. 程式碼覆蓋率

  • xdebug.mode=coverage 配合 PHPUnit 生成 clover.xml、crap4j.xml、HTML 報告。
  • CI/CD 整合:GitHub Actions、GitLab CI 中上傳覆蓋率報告至 Codecov、SonarCloud。

四、常見問題排查

現象原因與解決
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" 正確映射專案根目錄至容器/遠端路徑。

五、生產環境替代方案

  • Tideways:低開銷持續性能分析,支援 PHP 7.1+,無 Xdebug 重載問題。
  • Blackfire.io:SaaS 分析平台,按需觸發剖析,零持續開銷。
  • Swoole Tracker / OpenTelemetry:現代可觀測性棧整合。

Xdebug 是開發/測試環境的利器,生產環境請改用輕量級 APM 工具。

copyright © 萬盛學電腦網 all rights reserved