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
pecl install xdebug 或源碼編譯 (同 phpize 流程)。; 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"
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
systemctl restart php-fpm
php -m | grep xdebug
php -v | grep Xdebug
File → Settings → Languages & Frameworks → PHP → Debug:Xdebug port = 9003,勾選 "Can accept external connections"。Settings → PHP → Servers:添加 Server,Host=項目域名/IP,Port=80/443,勾選 "Use path mappings",映射本地項目路徑 ↔ 服務器絕對路徑。| 現象 | 排查方向 |
|---|---|
| php -m 無 xdebug | zend_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.remote_enable=1 → xdebug.mode=debug + xdebug.start_with_request=yes。「對版本下載 → zend_extension 載入 → 配置 mode/port/idekey → IDE 映射路徑 → 瀏覽器觸發」是 Xdebug 安裝調試的標準流程。掌握 TS/NTS、VC 版本、Path Mapping 三大塊點,能解決 90% 的安裝不生效問題。