PHP调试工具Xdebug安装与使用教程

安装配置Xdebug是PHP调试关键，需通过包管理或手动编译安装，配置php.ini启用扩展并设置远程调试参数，重启服务后验证模块加载，再结合VS Code等IDE设置监听端口与路径映射，即可实现断点调试。

要在PHP开发中高效排查问题，安装并配置调试工具 Xdebug 是非常关键的一步。Xdebug 是一个强大的 PHP 扩展，提供错误调试、堆栈跟踪、性能分析等功能。以下是 Xdebug 的安装与使用方法，适用于常见开发环境。

1. 安装 Xdebug 扩展

根据你的操作系统和 PHP 环境选择合适的安装方式：

方法一：通过包管理器安装（推荐 Linux）

如果你使用的是 Ubuntu/Debian 系统：

• sudo apt update
• sudo apt install php-xdebug

CentOS/RHEL 用户可使用 yum 或 dnf：

• sudo yum install php-pecl-xdebug
• sudo dnf install php-pecl-xdebug

方法二：手动下载编译（适用于自定义环境）

访问 https://xdebug.org/download 下载对应版本的源码包。

• tar -xvzf xdebug-3.x.x.tgz
• cd xdebug-3.x.x
• phpize
• ./configure --enable-xdebug
• make && sudo make install

安装完成后，扩展文件通常位于 /usr/lib/php/*/xdebug.so 或类似路径。

2. 配置 php.ini 启用 Xdebug

找到你的 php.ini 文件位置，可通过命令 php --ini 查看。

在 php.ini 中添加以下内容（Xdebug 3.x 示例）：

[xdebug]
zend_extension=xdebug.so
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log="/tmp/xdebug.log"

注意：

• 确保 zend_extension 指向正确的 .so 文件路径，如 /usr/lib/php/20220531/xdebug.so
• Xdebug 3 默认使用 9003 端口，不要与旧版 9000 混淆
• mode 设置为 debug 表示开启远程调试

保存后重启 Web 服务：

• Apache: sudo systemctl restart apache2
• PHP-FPM: sudo systemctl restart php-fpm
• 或重启 Nginx + PHP-FPM 组合

3. 验证 Xdebug 是否启用

创建一个 PHP 文件，写入：

在浏览器中访问该文件，搜索 “xdebug”。如果看到 Xdebug 模块信息，说明安装成功。

也可以在终端运行：

php -m | grep xdebug

若输出 xdebug，则扩展已加载。

4. 配合 IDE 使用调试功能（以 VS Code 为例）

使用 Xdebug 进行断点调试需要搭配支持的编辑器，如 VS Code、PhpStorm 等。

步骤：

• 安装 VS Code 插件：PHP Debug（由 Felix Becker 提供）
• 打开项目，在调试面板中点击“创建 launch.json”
• 配置如下内容：

{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceFolder}"
  }
}

说明： pathMappings 需将服务器路径映射到本地项目路径。

启动调试：

• 在 VS Code 中点击“开始监听”
• 浏览器访问目标页面，并添加参数 XDEBUG_SESSION_START=1，例如：
• http://localhost/test.php?XDEBUG_SESSION_START=1
• 或使用浏览器插件（如 Xdebug Helper）一键触发

当代码执行到断点时，VS Code 将自动暂停并显示变量状态，支持单步执行、查看调用栈等操作。

基本上就这些。安装 Xdebug 虽然涉及配置细节，但只要路径正确、端口匹配、IDE 设置无误，调试流程会很顺畅。建议初期开启 xdebug.log 查看连接日志，便于排错。