安装配置Xdebug是PHP调试关键，需通过包管理或手动编译安装，配置php.ini启用扩展并设置远程调试参数，重启服务后验证模块加载，再结合VS Code等IDE设置监听端口与路径映射，即可实现断点调试。
要在PHP开发中高效排查问题，安装并配置调试工具 Xdebug 是非常关键的一步。Xdebug 是一个强大的 PHP 扩展，提供错误调试、堆栈跟踪、性能分析等功能。以下是 Xdebug 的安装与使用方法，适用于常见开发环境。
1. 安装 Xdebug 扩展
根据你的操作系统和 PHP 环境选择合适的安装方式：
方法一：通过包管理器安装（推荐 Linux）
如果你使用的是 Ubuntu/Debian 系统：
立即学习“PHP免费学习笔记（深入）”；
- 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://www.php.cn/link/5f07196d710d5a71d68dfeb7b49db47f 下载对应版本的源码包。
- 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 文件，写入：
<?php phpinfo(); ?>
在浏览器中访问该文件，搜索 “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 查看连接日志，便于排错。
