PhpStorm + PHP8.1 + XDebug3 实现断点调试（亲测可用）

---

一、系统环境

1. PhpStorm 2024.1.1
   
2. php 8.1.29

php -v
PHP 8.1.29 (cli) (built: Jun  5 2024 10:43:14) (NTS Visual C++ 2019 x64)
Copyright (c) The PHP Group
Zend Engine v4.1.29, Copyright (c) Zend Technologieswith Zend OPcache v8.1.29, Copyright (c), by Zend Technologieswith Xdebug v3.1.0, Copyright (c) 2002-2021, by Derick Rethans
在 Windows 下进行 PhpStorm 配置 Xdebug3 之前，我们需要做好一些前期准备工作。这一步至关重要，它能为后续的配置过程奠定良好的基础，确保我们顺利搭建起高效的 PHP 开发调试环境。

3. XDebug 3.1.0
   

二、下载 Xdebug3 扩展

在准备好相关环境并确认好版本信息后，接下来我们就可以着手下载 Xdebug3 扩展了。这一步是实现 PhpStorm 与 Xdebug3 联动调试的关键，只有正确下载并安装了合适的 Xdebug3 扩展，我们才能顺利进行后续的调试工作。

2.1 确定 PHP 版本

准确确定当前系统中 PHP 的版本是下载正确 Xdebug3 扩展的首要前提。因为不同版本的 PHP 需要与之对应的 Xdebug3 扩展版本，若版本不匹配，可能会导致安装失败或在调试过程中出现各种问题。比如，使用了不兼容的扩展版本，可能会出现 “无法加载扩展” 的错误提示，或者在调试时无法正常设置断点、查看变量等。
确定 PHP 版本有多种便捷的方法：

• 命令行方式：如果你的系统已经配置了 PHP 的环境变量，那么在命令行中直接输入php -v，就能得到类似如下的输出：

PHP 8.1.29 (cli) (built: Jun  5 2024 10:43:14) (NTS Visual C++ 2019 x64)
Copyright (c) The PHP Group
Zend Engine v4.1.29, Copyright (c) Zend Technologieswith Zend OPcache v8.1.29, Copyright (c), by Zend Technologieswith Xdebug v3.1.0, Copyright (c) 2002-2021, by Derick Rethans

其中，“PHP 8.1.29” 就是当前 PHP 的版本号。若未配置环境变量，可先进入 PHP 的安装目录，再执行php -v命令。例如，若 PHP 安装在 “C:\php\php-8.1.29” 目录下，在命令行中先输入 “cd C:\php\php-8.1.29” 进入该目录，然后再输入php -v查看版本。

• 使用 phpinfo 函数：新建一个 PHP 文件，例如 “info.php”，在文件中写入如下代码：

<?php
phpinfo();
?>

将这个文件放置在 Web 服务器的可访问目录下（如 Apache 的 “htdocs” 目录或 Nginx 的对应目录），然后通过浏览器访问该文件，如 “http://localhost/info.php”。在打开的页面中，找到 “PHP Version” 一项，即可看到当前 PHP 的版本信息。同时，该页面还会展示许多其他关于 PHP 的配置信息，包括已安装的扩展、服务器环境等，这些信息在后续的开发和调试中也可能会用到。

2.2 下载对应扩展

确定好 PHP 版本后，就可以前往 Xdebug 官方下载地址：https://xdebug.org/download.php 进行扩展下载。

在该下载页面，会有一些选项需要我们根据实际情况进行选择：

• PHP Version：选择与我们前面确定的 PHP 版本一致的选项。比如，如果我们的 PHP 版本是 8.1.29，就选择对应的 “PHP 8.1.x” 选项。
• Thread Safety：这一项需要根据 PHP 的线程安全情况来选择。同样可以在前面通过phpinfo()函数生成的页面中查找 “Thread Safety” 字段，如果显示为 “enabled”，则表示 PHP 是线程安全的（TS），应选择 TS 版本的 Xdebug 扩展；若显示为 “disabled”，则表示是非线程安全的（NTS），应选择 NTS 版本的扩展 。选错线程安全类型的扩展，可能会导致在加载扩展时出现错误，影响后续调试工作的正常进行。

选择好相关选项后，页面会提供一个下载链接，点击即可下载对应的 Xdebug3 扩展文件，通常是一个以 “.dll” 结尾的文件，如 “php_xdebug-3.4.5-8.1-vs16-x86_64.dll”。下载完成后，务必记住文件的保存路径，因为在后。一般建议将其保存在 PHP 安装目录下的 “ext” 文件夹中，这样便于管理和查找，例如 “C:\php\php-8.1.10\ext” 。

三、配置 php.ini 文件

下载好 Xdebug3 扩展后，接下来需要对 php.ini 文件进行配置，以启用 Xdebug3 并设置相关参数。php.ini 是 PHP 的配置文件，通过对它的修改，我们可以调整 PHP 的运行时行为，使其满足我们的开发和调试需求。

3.1 找到 php.ini 文件

php.ini 文件的位置会因 PHP 的安装方式和所使用的环境不同而有所差异：

• 集成环境：如果使用的是集成开发环境，如 XAMPP、WAMP 或 MAMP 等，php.ini 文件通常位于集成环境的 PHP 安装目录中。例如，在 XAMPP 中，php.ini 文件可能位于 “C:\xampp\php” 目录下；在 WAMP 中，可能位于 “C:\wamp64\bin\php\php 版本号” 目录下。本人使用宝塔面板，目录为 “D:\BtSoft\php\81”。
  

• 独立安装：若是独立安装的 PHP，php.ini 文件一般在 PHP 的安装目录下。比如，PHP 安装在 “C:\php\php-8.1.10”，那么 php.ini 文件就在该目录中。如果不确定 php.ini 文件的位置，可以通过在 PHP 脚本中使用phpinfo()函数来查找。在 Web 服务器的可访问目录下创建一个 PHP 文件，例如 “find_php_ini.php” ，内容如下：

<?php
phpinfo();
?>

通过浏览器访问该文件，如 “http://localhost/find_php_ini.php” ，在输出的页面中搜索 “Loaded Configuration File” 一项，其对应的值就是当前 PHP 使用的 php.ini 文件的路径。

3.2 添加 Xdebug3 配置

找到 php.ini 文件后，使用文本编辑器（如 Notepad++、Sublime Text 等）打开它，然后在文件末尾添加以下 Xdebug3 的配置项：

[Xdebug]zend_extension=D:\BtSoft\php\ext\php_xdebug.dllxdebug.collect_params=1xdebug.collect_return=1xdebug.auto_trace=Offxdebug.trace_output_dir=D:\BtSoft\php\ext\php8.1.29nts.xdebug.tracexdebug.profiler_enable=Offxdebug.profiler_output_dir=D:\BtSoft\php\ext\php8.1.29nts.xdebug.profilerxdebug.client_enable=Onxdebug.client_host=127.0.0.1xdebug.client_port=9003xdebug.remote_handler=dbgpxdebug.idekey=PHPSTORMxdebug.mode=debug

3.3 保存并重启服务器

添加完上述配置后，务必保存 php.ini 文件的修改。然后，重启 Web 服务器，使新的配置生效。如果使用的是集成开发环境，如 XAMPP 或 WAMP，可以通过它们的控制面板来重启 Apache 服务；若是独立安装的 Apache 或 Nginx 服务器，则需要使用相应的命令来重启服务。例如，在 Windows 系统中，若使用的是 Apache 服务器，可以在命令提示符中以管理员身份运行以下命令来重启 Apache 服务：

net stop apache
net start apache

对于 Nginx 服务器，假设 Nginx 的安装目录为 “C:\nginx” ，可以在命令提示符中运行以下命令来重启服务：

C:\nginx\nginx.exe -s stop
C:\nginx\nginx.exe

宝塔面板下重启对应的网站即可。

重启服务器后，Xdebug3 就已经在 PHP 环境中成功配置好了，接下来就可以在 PhpStorm 中进行相关设置，实现两者的联动调试。

四、PhpStorm 配置

在完成了 Xdebug3 在 PHP 环境中的配置后，接下来我们需要在 PhpStorm 中进行相应的设置，以实现两者的联动调试。通过正确的 PhpStorm 配置，我们能够充分利用 Xdebug3 强大的调试功能，更高效地进行 PHP 项目的开发。

4.1 打开设置界面

启动 PhpStorm 后，点击菜单栏中的 “File” 选项，在弹出的下拉菜单中选择 “Settings” 。这将打开 PhpStorm 的设置窗口，该窗口包含了众多的配置选项，我们可以在这里对 PhpStorm 的各种功能和行为进行定制。在设置窗口的左侧，有一个树形结构的导航栏，我们需要在其中找到 “PHP” ，这里就是与 PHP 开发相关的设置入口，后续我们对 PHP 解释器、调试器等的配置都将在此处进行。点击 “PHP”，设置 PHP language level 和 CLI Interpreter：

4.2 设置 Debug 配置

在 “PHP” 设置页面中，选择 “Debug” 选项卡 。在这里，我们需要进行一些关键的调试配置：

• 设置端口号：在 “Debug port” 字段中，输入与 php.ini 中xdebug.client_port配置相同的端口号，例如 “9003” 。这个端口号是 PhpStorm 与 Xdebug3 进行通信的端口，确保两者一致才能建立有效的连接，实现调试功能。如果端口号不一致，PhpStorm 将无法接收到 Xdebug3 发送的调试信息，导致无法进行断点调试、变量查看等操作。
• 勾选接收外部连接：勾选 “Accept external connections” 选项 。这一选项允许 PhpStorm 接收来自外部的调试连接，在我们使用 Xdebug3 进行调试时，Xdebug3 会作为外部连接向 PhpStorm 发送调试信息，勾选此选项后，PhpStorm 才能正确接收并处理这些信息，从而进行调试工作。
  

4.3 设置服务器配置

在 “PHP” 设置页面中，点击 “Servers” 选项卡，然后点击右上角的 “+” 按钮，添加一个新的服务器配置：

• 设置服务器名称：在 “Name” 字段中，输入一个易于识别的服务器名称，比如 “Local Server” 。这个名称只是为了方便我们在 PhpStorm 中区分不同的服务器配置，可根据实际情况自定义。
• 设置主机和端口：在 “Host” 字段中，输入服务器的主机地址，一般本地开发环境中设置为 “127.0.0.1” ；在 “Port” 字段中，输入 Web 服务器的端口号，如常见的 “80” 或 “8080” ，这要根据实际使用的 Web 服务器端口来填写。
• 选择调试器：在 “Debugger” 下拉菜单中，选择 “Xdebug” ，明确告诉 PhpStorm 使用 Xdebug 作为调试器。
• 配置路径映射：这一步非常重要，它确保 PhpStorm 能够正确映射服务器上的文件路径和本地项目中的文件路径。在 “Path mappings” 区域，“Local path” 表示本地项目的路径，一般会自动识别并显示当前打开项目的路径；“Deployment path” 表示服务器上对应的项目路径，例如在 XAMPP 中，可能是 “C:\xampp\htdocs\ 项目名称” 。确保两者的路径映射正确，才能在调试时准确地定位和修改代码。例如，如果本地项目路径是 “D:\Projects\MyPHPProject” ，而服务器上的项目路径是 “C:\xampp\htdocs\MyPHPProject” ，在 “Path mappings” 中就需要正确配置这两个路径的对应关系，否则在调试时可能会出现找不到文件或文件内容不一致的问题。
  
  完成以上配置后，点击 “Apply” 和 “OK” 按钮保存设置，至此，PhpStorm 中关于 Xdebug3 的配置就全部完成了，接下来就可以进行调试工作了。

4.4 设置 DBGp Proxy

点击 “PHP” -> “Debug” -> “DBGp Proxy”，进行如下设置：

4.5 校验

点击 “PHP” -> “Debug” 页面的 “Validate” 按钮：

在跳出的页面选中 “Local Web Server or Shared Folder”，进行设置后点击【Validate】按钮：

出现以下信息说明配置成功：

五、验证配置是否成功

在完成了前面一系列关于 Windows 下 PhpStorm 配置 Xdebug3 的步骤后，我们还需要进行最后的验证，确保整个配置过程成功无误，Xdebug3 能够在 PhpStorm 中正常工作，为我们的 PHP 开发提供高效的调试支持。

5.1 创建测试文件

首先，在我们的 PHP 项目中创建一个简单的测试文件，比如 “test.php”。这个文件的作用是帮助我们验证 Xdebug3 和 PhpStorm 的配置是否成功，通过在其中编写一些简单的 PHP 代码，来测试调试功能是否正常。在 “test.php” 中，我们可以编写如下代码：

<?php
$name = "John";
$age = 30;
$result = $name. " is ". $age. " years old.";
echo $result;
?>

这段代码定义了两个变量$name和$age，然后将它们组合成一个字符串并赋值给$result变量，最后输出这个结果。接下来，我们要在这个文件中设置断点。断点是调试过程中的关键，它能让程序在执行到指定位置时暂停，以便我们查看变量的值、执行流程等信息。在 PhpStorm 中，找到 “test.php” 文件，在代码行的左侧空白区域点击，会出现一个红色的圆点，这就是断点。例如，我们可以在$result = $name. " is “. $age. " years old.”;这一行设置断点，当程序执行到这一行时，就会暂停下来，方便我们进行调试操作。

5.2 浏览器安装 Xdebug helper 插件

浏览器安装 Xdebug helper 插件，本文使用 Edge 浏览器进行安装：

需要设置插件的 IDE key：

5.3 启动调试

设置好断点后，就可以在 PhpStorm 中启动调试了。点击 PhpStorm 工具栏上的绿色小虫子图标，这个图标代表启动调试会话。如果之前没有配置过调试配置，会弹出一个选择配置的窗口，选择我们之前在 PhpStorm 中配置的服务器（例如前面设置的 “Local Server”） ，然后点击 “Debug” 按钮 。此时，PhpStorm 会开始监听指定的调试端口（如 9003），等待 Xdebug3 发送调试信息。接下来，通过浏览器访问我们的测试文件 “test.php” ，在浏览器地址栏中输入测试文件的 URL，例如 “http://localhost/test.php” （这要根据前面在 PhpStorm 中配置的服务器主机和端口以及项目路径来确定）。当浏览器加载这个页面时，Xdebug3 会捕获到这个请求，并将调试信息发送给 PhpStorm。如果配置成功，我们会看到 PhpStorm 的界面切换到调试模式，代码执行到我们设置的断点处暂停下来，此时，我们就可以开始进行调试操作了。

5.4 查看调试信息

当程序在断点处暂停后，我们可以查看各种调试信息，以此来判断配置是否成功。在 PhpStorm 的调试工具窗口中，可以看到以下关键信息：

• 变量值：在 “Variables” 面板中，可以看到当前作用域内所有变量的值。例如，我们可以看到$name的值为 “John”，$age的值为 30，$result的值还未计算（因为程序暂停在赋值语句之前） 。通过查看变量值，我们可以验证程序是否按照我们预期的方式运行，是否存在变量赋值错误等问题。
• 调用堆栈：“Call Stack” 面板展示了当前程序执行的函数调用堆栈信息。它显示了从程序入口开始，到当前断点处，函数的调用顺序和层次关系。这对于理解复杂程序的执行流程非常有帮助，当出现函数调用错误或逻辑混乱时，通过调用堆栈可以快速定位问题所在。比如，在一个多层嵌套的函数调用中，如果出现错误，查看调用堆栈就能清晰地看到是从哪个函数开始出现异常的。
• 调试操作按钮：PhpStorm 提供了一系列调试操作按钮，如 “Step Over”（单步执行，执行当前行代码并跳到下一行，但不会进入函数内部）、“Step Into”（单步执行并进入函数内部）、“Step Out”（从当前函数中跳出）等 。通过这些按钮，我们可以逐行执行代码，观察程序的执行过程，进一步排查问题。

如果能够顺利地查看这些调试信息，并通过调试操作按钮控制程序的执行，就说明我们在 Windows 下 PhpStorm 配置 Xdebug3 的过程是成功的，后续就可以在实际的 PHP 项目开发中利用这一强大的调试工具，提高开发效率，快速解决代码中的问题。

六、常见问题及解决方法

在配置 Windows 下 PhpStorm 与 Xdebug3 的过程中，可能会遇到一些问题，影响调试工作的正常进行。下面为大家列举一些常见问题，并提供相应的解决方法。

6.1 无法进入断点

• 问题描述：在 PhpStorm 中设置断点后，启动调试并通过浏览器访问相关 PHP 页面，但程序并未在断点处暂停，而是直接运行完成，无法进行调试操作。
• 可能原因：
  • 配置错误：php.ini 文件中 Xdebug3 的配置可能存在问题，例如xdebug.mode未设置为debug，或者xdebug.start_with_request未设置为yes，导致 Xdebug3 没有正常启动调试会话。
  • 端口冲突：PhpStorm 设置的调试端口与其他程序占用的端口冲突，使得 Xdebug3 无法与 PhpStorm 建立通信连接，从而无法触发断点。
  • 路径映射错误：PhpStorm 中配置的服务器路径映射与实际项目路径不一致，导致 PhpStorm 无法正确定位到代码文件，进而无法在断点处暂停。
• 解决方法：
  • 检查配置：仔细检查 php.ini 文件中的 Xdebug3 配置项，确保xdebug.mode = debug和xdebug.start_with_request = yes，并且其他配置项如zend_extension指定的扩展路径正确无误。同时，检查 PhpStorm 中的调试配置，确保Debug port与 php.ini 中xdebug.client_port设置一致。
  • 排查端口冲突：使用命令行工具（如netstat -ano）查看当前系统中占用调试端口（如 9300）的进程，若发现有冲突的进程，可尝试关闭该进程，或者在 php.ini 和 PhpStorm 中修改调试端口为其他未被占用的端口，如 9301。
  • 确认路径映射：在 PhpStorm 的 “Servers” 设置中，仔细核对 “Path mappings” 区域的本地路径和部署路径是否与实际项目路径一致。若不一致，手动修改为正确的路径，确保代码文件的正确映射。

6.2 端口冲突

• 问题描述：在设置调试端口时，提示端口已被占用，无法使用指定的端口进行调试。
• 可能原因：系统中其他正在运行的程序占用了我们计划用于调试的端口，比如某些 Web 服务器、数据库管理工具或者其他调试工具等。
• 解决方法：
  • 查找占用端口的进程：在命令提示符中输入netstat -ano | findstr :端口号（例如netstat -ano | findstr :9003），可以查看到占用该端口的进程 ID（PID）。
  • 结束占用进程：打开任务管理器，在 “详细信息” 选项卡中找到对应的 PID，右键点击该进程，选择 “结束任务” 来关闭占用端口的程序。如果不确定该进程是什么程序，可以通过搜索引擎查询 PID 对应的程序名称。
  • 修改调试端口：若不想结束占用端口的程序，可在 php.ini 和 PhpStorm 中同时修改调试端口为其他未被占用的端口。修改完成后，记得重启 Web 服务器和 PhpStorm，使新的端口设置生效。

6.3 找不到 Xdebug 扩展

• 问题描述：在重启 Web 服务器后，出现 “无法加载 Xdebug 扩展” 的错误提示，导致 Xdebug3 无法正常工作。
• 可能原因：
  • 扩展路径错误：在 php.ini 文件中配置的zend_extension路径不正确，无法找到对应的 Xdebug3 扩展文件。
  • 文件损坏：下载的 Xdebug3 扩展文件可能在下载过程中损坏，导致无法正常加载。
• 解决方法：
  • 检查扩展路径：再次确认 php.ini 中zend_extension配置的路径是否与实际 Xdebug3 扩展文件的存放路径一致。若不一致，修改为正确的路径。例如，如果扩展文件存放在 “C:\php\php-8.1.10\ext\php_xdebug-3.1.5-8.1-vs16-x86_64.dll” ，则zend_extension应配置为该路径。
  • 重新下载扩展：若怀疑扩展文件损坏，可前往 Xdebug 官方网站重新下载对应版本的扩展文件，并替换原来的文件。下载完成后，再次重启 Web 服务器，检查是否能正常加载扩展。