第167篇：PHPStorm + phpStudy + Xdebug 断点调试环境配置踩坑全记录

原创

abc123info
abc123info

希潭实验室

2026年7月1日 17:58
山东

在小说阅读器读本章

去阅读

Part1 前言

大家好，我是 ABC\_123。这两天又碰上了 PhpStorm 配合 PhpStudy 接入 Xdebug 进行 PHP 断点调试的问题。每次遇到它，都得翻一堆资料、踩不少坑才能调通，这次也不例外。索性把整个折腾的过程记录下来，分享给大家，希望大家少走弯路。

Part2 技术研究过程

基础知识

Xdebug 调试分为直连模式和代理模式两种。代理模式通常用于多人共用一台开发服务器进行调试（通过 idekey 区分不同开发者），或远程服务器调试、IDE 位于内网无法被 Xdebug 直接连接等场景；而本地单机配合 localhost 调试时，绝大多数情况下使用直连模式即可，无需额外部署 DBGP 代理。

工作流程：

1 首先启动 dbgpProxy.exe 并监听 9001 端口。

2 PHPStorm 注册到代理，连接 9001 端口，并向代理发送 REGISTER 请求，注册自己的 idekey = PHPSTORM，表示：\"以后凡是 idekey=PHPSTORM 的调试连接，请转发给我\"。

3 Xdebug 发起调试连接，根据 xdebug.client\_host 和 xdebug.client\_port（或 Xdebug 2 的 xdebug.remote\_host、xdebug.remote\_port）连接到 9001 端口，并在 DBGP 初始化报文中携带相同的 idekey = PHPSTORM。

4 dbgpProxy 查找注册表，根据 idekey 找到对应的 IDE 连接，然后将该调试会话转发给 PHPStorm，之后 Xdebug 与 PHPStorm 的所有调试数据都通过代理进行转发。

需要注意的是，PHPStorm 中的“DBGP 代理端口（9001）”配置仅在已启动 dbgpProxy.exe 且代理监听该端口时才会生效；如果没有启动代理，这项配置不会发挥任何作用，也不会影响 Xdebug 的连接目标。

PhpStudy环境 + Xdebug 安装配置

选择新版phpstudy的小皮版本，也就是phpstudy V8.1版本，php版本选择 php7.3.4nts。

接着设置phpstudy的php扩展插件，勾选xdebug插件。

核心配置：php.ini 与 PhpStorm 双端设置，

切换到如下界面，修改php.ini配置文件，对xdebug进行配置，Xdebug是发起调试的客户端，PHPStorm是接收调试的服务端。这里面有一个坑，由于 Xdebug 早期版本默认使用 9000 作为调试端口，而部分 PHP 环境（如 PHP-CGI、PHP-FPM）默认也会占用 9000 端口，因此可能发生端口冲突。当 PHPStorm 监听 9000 端口时，Xdebug 发起的调试连接可能无法正常建立。为避免冲突，建议将 Xdebug 的调试端口修改为 9003，并将 PHPStorm 的监听端口同步配置为 9003。Xdebug 3 也已将默认调试端口调整为 9003，因此推荐优先使用该端口。

将xdebug.remote\_enable = On 开启。配置dbgp代理及 idekey 为 PHPSTORM。

具体配置如下：

[Xdebug]zend_extension=D:/1WebSite/phpstudy_pro/Extensions/php/php7.3.4nts/ext/php_xdebug.dllxdebug.collect_params=1xdebug.collect_return=1xdebug.auto_trace=Offxdebug.trace_output_dir=D:/1WebSite/phpstudy_pro/Extensions/php_log/php7.3.4nts.xdebug.tracexdebug.profiler_enable=Offxdebug.profiler_output_dir=D:/1WebSite/phpstudy_pro/Extensions/php_log/php7.3.4nts.xdebug.profilerxdebug.remote_enable=Onxdebug.remote_host=localhostxdebug.remote_port=9003xdebug.remote_handler=dbgpxdebug.remote_mode = reqxdebug.idekey = PHPSTORM

配置PHP CLI解析器

打开phpstorm，添加phpstudy目录下的php.exe。

如图所示，添加php.exe之后，手工选择配置文件的路径及调试器扩展的路径。

调试功能菜单下的Xdebug功能的调试端口 9003,9000要包含上述php.ini中配置的9003。

DBGp代理配置，填好前面我们设置的PHPSTORM及主机域名。

配置服务器：主机(H) 配置为 localhost + 端口8001，表示你的 PHP 项目通过 http://localhost:8001 访问。注意：这里的端口 8001 是 Web 服务器端口，不是 Xdebug 的调试端口9003，调试时 PhpStorm 会自动生成形如 http://localhost:8001/?XDEBUG\_SESSION\_START=PHPSTORM 的 URL。