萬盛學電腦網

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

PHP 安裝 Xdebug 擴展完整指南:配置遠程調試與性能分析

安裝步驟

1. 確定 PHP 版本與編譯參數

php -v
# PHP 7.4.33 (cli) (built: ... ) ( NTS )  ← 關鍵:NTS (Non-Thread Safe) 或 TS
php -i | grep "extension_dir"
# extension_dir => /usr/local/php/lib/php/extensions/no-debug-non-zts-20190902

2. 下載對應版本 DLL/so

  • Windows:Xdebug 官網下載頁 → 選擇 PHP 版本、TS/NTS、VC 版本 (VC15/VS2017 等)。
  • Linux:pecl install xdebug 或源碼編譯 (同 phpize 流程)。

3. 放置文件並修改 php.ini

; Windows 示例
zend_extension = "C:/php/ext/php_xdebug-3.2.1-7.4-vc15-nts-x86_64.dll"

; Linux 示例
zend_extension = "/usr/local/php/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so"

; 通用調試配置 (Xdebug 3.x 語法)
xdebug.mode = debug,develop,profile,trace
xdebug.start_with_request = yes
xdebug.client_host = "127.0.0.1"
xdebug.client_port = 9003
xdebug.log = "/tmp/xdebug.log"
xdebug.log_level = 7

; 性能分析輸出目錄 (需可寫權限)
xdebug.profiler_output_dir = "/tmp/xdebug_profiler"
xdebug.trace_output_dir = "/tmp/xdebug_trace"

; IDE Key (PhpStorm/VS Code 配置一致)
xdebug.idekey = "PHPSTORM"

4. 創建輸出目錄並設置權限

mkdir -p /tmp/xdebug_profiler /tmp/xdebug_trace
chown www:www /tmp/xdebug_profiler /tmp/xdebug_trace
chmod 755 /tmp/xdebug_profiler /tmp/xdebug_trace

5. 重啟 PHP-FPM 並驗證

systemctl restart php-fpm
php -m | grep xdebug
php -v | grep Xdebug

IDE 配置 (以 PhpStorm 為例)

  1. File → Settings → Languages & Frameworks → PHP → Debug:Xdebug port = 9003,勾選 "Can accept external connections"。
  2. Settings → PHP → Servers:添加 Server,Host=項目域名/IP,Port=80/443,勾選 "Use path mappings",映射本地項目路徑 ↔ 服務器絕對路徑。
  3. 工具欄點擊「Start Listening for PHP Debug Connections」電話圖標變綠。
  4. 瀏覽器安裝 Xdebug Helper 擴展,設置 IDE Key = PHPSTORM,點擊 Debug 圖標變綠。
  5. 在代碼打斷點,訪問頁面 → PhpStorm 彈出調試界面。

常見問題排查

現象排查方向
php -m 無 xdebugzend_extension 路徑錯誤、TS/NTS 不匹配、VC 版本不匹配、php.ini 未生效 (php --ini 確認)
斷點不生效Path Mapping 錯誤、xdebug.mode 缺少 debug、client_host/port 不通、防火牆阻擋 9003
性能極慢關閉 profile/trace 模式 (xdebug.mode=debug),僅調試時開啟
日志無輸出xdebug.log 路徑不可寫、log_level 太低

Xdebug 2.x vs 3.x 關鍵差異

  • 配置指令簡化:xdebug.remote_enable=1 → xdebug.mode=debug + xdebug.start_with_request=yes。
  • 默認端口:9000 → 9003 (避免與 PHP-FPM 9000 衝突)。
  • 性能開銷大幅降低 (按需編譯、JIT 友好)。

總結

「對版本下載 → zend_extension 載入 → 配置 mode/port/idekey → IDE 映射路徑 → 瀏覽器觸發」是 Xdebug 安裝調試的標準流程。掌握 TS/NTS、VC 版本、Path Mapping 三大塊點,能解決 90% 的安裝不生效問題。

copyright © 萬盛學電腦網 all rights reserved