Ubuntu 下安裝配置 Xdebug 完整指南

在 Ubuntu 環境下通過 PECL 安裝 Xdebug，避免手動編譯麻煩，快速構建 PHP 調試環境。

前置依賴安裝

sudo apt-get update
sudo apt-get install php-pear php5-dev
# php-pear 提供 pecl 命令
# php5-dev 提供 phpize 編譯工具

安裝 Xdebug

sudo pecl install xdebug
# 過程：下載源碼 → 自動 phpize → configure → make → make install
# 成功後會提示：install ok: channel://pecl.php.net/xdebug-
# 並顯示 .so 文件路徑，如：/usr/lib/php/20131226/xdebug.so

配置 php.ini

編輯 /etc/php5/apache2/php.ini (Apache) 或 /etc/php5/cli/php.ini (CLI) 或 /etc/php5/fpm/php.ini (PHP-FPM)：

; 載入擴展
extension=xdebug.so

; Zend 引擎模式（某些版本需要雙重聲明）
[xdebug]
zend_extension="/usr/lib/php/20131226/xdebug.so"

; 基礎調試配置
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.idekey="PHPSTORM"

重啟服務驗證

sudo service apache2 restart
# 或
sudo service php5-fpm restart

# 驗證
php -m | grep xdebug
php -i | grep xdebug

常見問題排查

現代版本提示 (Ubuntu 18.04+ / PHP 7.2+)

sudo apt-get install php-xdebug
# 官方源直接提供，無需 pecl 編譯

# 配置文件通常在 /etc/php/7.x/mods-available/xdebug.ini
# 通過 phpenmod 啟用
sudo phpenmod xdebug

IDE 整合 (PhpStorm 為例)

1. Settings → Languages & Frameworks → PHP → Debug → Xdebug：Port 9000/9003，IDE Key PHPSTORM
2. Settings → Languages & Frameworks → PHP → Servers：添加項目映射（本地路徑 ↔ 服務器路徑） 3. 瀏覽器安裝 Xdebug Helper 擴展，設置 IDE Key 4. PhpStorm 點擊「Start Listening for PHP Debug Connections」 5. 瀏覽器訪問項目，斷點生效

遵循標準化安裝流程，Xdebug 部署不再是難題，專注於代碼質量提升。