目录
- 前置准备
- 1 确认环境
- 2 安装 Xdebug 扩展
- 3 获取 Xdebug 信息
- PHPStorm 配置
- 1 配置 PHP 解释器
- 2 配置 DBGp 代理
- 3 配置调试选项
- 开始调试
- 1 在代码中设置断点
- 2 启动调试会话
- 3 执行代码并查看结果
- 常见问题与解决方案
- 1 PhpStorm 无法连接到 Xdebug
- 2 Xdebug 版本不匹配
- 3 调试时浏览器无法触发
- 高级技巧与最佳实践
- 1 配置浏览器一键调试
- 2 远程服务器调试
- 3 变量求值与表达式执行
- 4 调整性能（
xdebug.mode=debugvsxdebug.profiler）
前置准备
在开始之前，请确保你已经安装了 PHPStorm 和一个本地或远程的 PHP 环境（如 Docker, MAMP, WAMP, 或原生安装）。
1 确认环境
打开你的终端（Windows 是 CMD 或 PowerShell，macOS/Linux 是 Terminal），运行以下命令检查 PHP 版本和已安装的扩展：
php -v php -m | grep xdebug
php -v没有输出，说明 PHP 没有添加到系统环境变量。php -m | grep xdebug没有输出，说明 Xdebug 扩展尚未安装,我们需要先安装它。
2 安装 Xdebug 扩展
Xdebug 的安装方式取决于你的 PHP 环境和操作系统，最推荐的方式是使用 PECL。
-
安装 PECL：
- macOS (使用 Homebrew):
brew install php - Linux (Debian/Ubuntu):
sudo apt-get install php-pear php-dev - Windows: PECL 通常随 PHP 安装包一同提供，位于
php\pear目录下。
- macOS (使用 Homebrew):
-
安装 Xdebug： 运行以下命令。请务必使用你的 PHP 版本对应的 Xdebug 版本,否则会不兼容。
（图片来源网络，侵删）pecl install xdebug
-
配置
php.ini： 安装完成后，PECL 会告诉你 Xdebug 的配置文件位置（通常是php.ini），你需要手动将zend_extension=xdebug这一行添加到你的php.ini文件中。-
重要: 确保
zend_extension=xdebug这一行没有被注释（前面没有 ），并且放在其他zend_extension指令之后。 -
Windows:
zend_extension = "C:\path\to\php\ext\xdebug.dll" -
Linux/macOS:
zend_extension=xdebug
（图片来源网络，侵删）
-
-
重启你的 Web 服务器（如 Apache/Nginx）或 PHP-FPM,以使配置生效。
3 获取 Xdebug 信息
为了确保 Xdebug 正确安装，并在后续步骤中找到正确的配置，我们需要获取 Xdebug 的详细信息,在终端运行：
php -i | grep xdebug
你会看到类似下面的输出，请务必记下 xdebug.mode 和 xdebug.client_host 的值。xdebug.mode 是 off，说明 php.ini 配置有误。
xdebug
...
xdebug.mode => debug => debug
xdebug.client_host => localhost => localhost
...PHPStorm 配置
我们开始在 PHPStorm 中进行配置。
1 配置 PHP 解释器
PHPStorm 需要知道要使用哪个 PHP 版本来运行和调试你的代码。
- 打开 PHPStorm，进入
Settings/Preferences(macOS:PHPStorm->Settings, Windows/Linux:File->Settings)。 - 导航到
Languages & Frameworks->PHP。 - 在
PHP language level下，点击CLI Interpreter右侧的 按钮。 - 如果没有配置过解释器，点击 号，选择
From local web server或CLI Interpreter。 - PHPStorm 会自动扫描并列出你系统中安装的 PHP，选择与你的 Web 服务器和终端使用的 同一个 PHP 版本。
- 如果没有自动检测到，可以点击 按钮，手动指定 PHP 可执行文件的路径（
/usr/bin/php或C:\php\php.exe）。 - 点击
OK保存。
2 配置 DBGp 代理
这是连接 PHPStorm 和 Xdebug 的关键步骤。
- 仍然在
Settings/Preferences中，导航到Languages & Frameworks->Debug。 - 在
Debug port中，输入9003，这是 Xdebug 3 默认的调试端口。- 注意: 如果你使用的是 Xdebug 2，默认端口是
9000，请根据你的 Xdebug 版本进行修改。
- 注意: 如果你使用的是 Xdebug 2，默认端口是
- （可选但推荐） 勾选
Can accept external connections，这样 PHPStorm 就能监听来自任何来源的调试连接。 - 点击
OK保存。
3 配置调试选项
这个选项决定了 PHPStorm 如何处理传入的调试请求。
- 在
Settings/Preferences中，导航到Languages & Frameworks->Debug->Debug Options。 Break at first line: 勾选此项，当调试会话开始时，PHPStorm 会在你代码的第一行（通常是index.php）自动暂停,这对于确认调试是否正常工作非常有用。Validate existing open files: 勾选此项，PHPStorm 只为你已经打开的文件设置断点,这可以防止在你不关心的代码中意外暂停。Use path mappings: 非常重要！ 这一步将服务器上的文件路径映射到 PHPStorm 中的项目路径。- 点击 按钮,打开路径映射设置。
- 在
Server path中，输入你的项目在 Web 服务器上的根目录路径（/var/www/html或C:\xampp\htdocs\my-project）。 - 在
Local path中，选择 PHPStorm 中对应的项目文件夹。 - 点击
OK保存。
开始调试
配置完成后,我们终于可以开始享受调试的乐趣了。
1 在代码中设置断点
在你想要暂停执行的代码行号左侧的空白处，单击鼠标左键，你会看到一个红色的圆点,这就是断点。
<?php
// index.php
function add($a, $b) {
return $a + $b; // <-- 在这里设置一个断点
}
$result = add(5, 10);
echo "The result is: " . $result;
?>
2 启动调试会话
有三种主要方式启动调试会话：
-
使用“调试”按钮（最常用）
- 确保你的代码在浏览器中可以访问（
http://localhost/my-project/index.php）。 - 在 PHPStorm 的右上角工具栏中，找到并点击 “Debug” 按钮（一个绿色的虫子图标）。
- PHPStorm 会启动一个内置的 Web 服务器（或使用你配置的服务器）,并打开一个浏览器窗口访问你的项目。
- 当代码执行到你设置的断点时，程序会自动暂停，PHPStorm 会切换到调试界面。
- 确保你的代码在浏览器中可以访问（
-
使用“运行”按钮
- 点击右上角的 “Run” 按钮（一个绿色的播放图标）。
- 这会以“运行”模式启动，不会触发断点，但你可以通过其他方式（见下一节）来触发调试。
-
通过浏览器触发（最灵活） 这是最推荐的方式,因为它与你的日常开发流程无缝集成。
3 执行代码并查看结果
当程序在断点处暂停时，你会看到 PHP 界面被分割成几个关键区域：
-
调试工具窗口：
- Frames (调用栈): 显示了当前函数调用的层级，你可以点击不同的栈帧,查看该层级下的变量和上下文。
- Variables (变量): 显示了当前作用域内所有变量的值，你可以展开数组、对象,查看其内部结构。
- Watches (监视): 你可以在这里添加表达式或变量名，PHPStorm 会持续跟踪它们的值。
- Debug (调试控制): 包含了最重要的调试操作按钮。
-
调试控制按钮：
Resume Program(F9): 继续执行,直到下一个断点或程序结束。Step Over(F8): 在当前行执行，如果当前行是函数调用,则进入该函数但不进入其内部。Step Into(F7): 如果当前行是函数调用，则进入该函数内部，否则,执行当前行。Force Step Over(Shift+F8): 类似于Step Over，但如果当前行是函数调用,会完整执行该函数而不进入。Step Out(Shift+F8): 从当前函数中执行到函数返回处,然后暂停。Run to Cursor(Alt+F9): 执行代码,直到光标所在的行。
常见问题与解决方案
1 PhpStorm 无法连接到 Xdebug
这是最常见的问题,通常由以下原因引起：
- 端口不匹配：检查
php.ini中的xdebug.client_port和 PHPStormSettings中的Debug port是否一致（默认都是9003）。 - Xdebug 未加载：在终端运行
php -m | grep xdebug，确认 Xdebug 已安装并加载。 - 防火墙/杀毒软件：检查 Windows Defender 或其他防火墙是否阻止了 PhpStorm 监听端口。
php.ini配置错误：检查zend_extension=xdebug是否正确无误,并且没有被注释。- 路径映射错误：确保
Settings->Debug->Use path mappings中的路径是正确的。
2 Xdebug 版本不匹配
- 现象: PHPStorm 提示 "Xdebug 3.x is not compatible with the IDE key 'pstorm'..."。
- 解决方案: Xdebug 3 和 Xdebug 2 在配置和功能上有很大差异。强烈建议升级到 Xdebug 3。
- 如果你必须使用 Xdebug 2，请将
php.ini中的配置从zend_extension和xdebug.mode改为旧格式：zend_extension=xdebug xdebug.remote_enable=1 xdebug.remote_autostart=1 xdebug.remote_host=localhost xdebug.remote_port=9000
- 将 PHPStorm 的
Debug port改为9000。
- 如果你必须使用 Xdebug 2，请将
3 调试时浏览器无法触发
- 检查 Xdebug 状态: 在浏览器中访问
https://xdebug.tools，这个网站会检测你的请求中是否带有 Xdebug 的 Cookie，并告诉你 Xdebug 是否正在工作，如果显示 "No Xdebug detected"，说明 Xdebug 没有被触发。 - 检查 IDE Key: 在
php.ini中，确保xdebug.idekey设置为pstorm（这是 PHPStorm 的默认值），或者与 PHPStorm 设置中的IDE key一致。 - 使用 Xdebug Helper 浏览器扩展: 安装浏览器扩展（如 Chrome 的 "Xdebug Helper"）可以手动开启/关闭调试，并选择 IDE Key,非常方便。
高级技巧与最佳实践
1 配置浏览器一键调试
安装浏览器扩展（如 "Xdebug Helper"）后，你可以在浏览器工具栏中点击扩展图标，选择 "PHPStorm" 作为 IDE，之后，当你访问一个网页时，只需点击扩展图标，选择 "Debug"，即可自动将调试信息发送到正在运行的 PHPStorm。
2 远程服务器调试
如果你的代码运行在远程的 Docker 容器或云服务器上，配置方法类似，但关键在于 xdebug.client_host。
- 在远程服务器的
php.ini中:- 将
xdebug.client_host设置为你本地机器的 IP 地址，而不是localhost。 xdebug.client_host=192.168.1.100
- 将
- 在 PHPStorm 的
Settings->Languages & Frameworks->Servers中:- 添加一个新的服务器配置，填入远程服务器的 SFTP/FTP 信息，并正确配置路径映射。
- 在调试工具窗口中选择服务器:
在调试工具栏的下拉菜单中,选择你刚刚配置的远程服务器。
3 变量求值与表达式执行
在调试过程中,你可以：
- 查看变量: 在
Variables窗口中直接查看。 - 添加监视: 在
Watches窗口中输入变量名或表达式（如$user->getRoles()）,实时查看结果。 - 求值表达式: 在调试工具窗口的任何地方，右键点击 ->
Evaluate Expression(快捷键Alt+F8)，可以执行任意 PHP 代码并查看结果。
4 调整性能
Xdebug 会显著降低 PHP 的执行速度，在生产环境中绝对不要启用它。
xdebug.mode=debug: 这是调试模式，会开启所有调试功能,影响性能最大。xdebug.profiler: 这是性能分析模式，用于生成性能分析报告（如 cachegrind 文件），帮助你找到代码瓶颈，你可以通过xdebug.mode=profile来单独开启它,与调试模式分离。
通过以上步骤，你就可以在 PHPStorm 中熟练使用 Xdebug 进行高效的代码调试了,祝你编码愉快！
