PhpStorm调试Laravel9 Pest测试失败：Xdebug连接未建立

环境信息 #

本地配置 #

• PhpStorm版本：2022.3.2
• macOS版本：13.2.1 (22D68)

Xdebug配置（php.ini） #

[xdebug]
zend_extension="xdebug.so"
xdebug.mode=develop,coverage,debug,profile
xdebug.idekey=PHPSTORM
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9001
xdebug.client_host=127.0.0.1

问题描述 #

Laravel 9项目的Pest测试可正常运行，但在PhpStorm中给测试代码设置断点并启动调试时，出现以下异常：

1. 调试器持续等待incoming connection（截图：调试等待连接）
2. 提示连接未建立（截图：连接未建立提示）
3. 提示Xdebug 3.2.0已安装，但连接未建立，请检查配置（截图：Xdebug配置检查提示）

排查与修复步骤 #

1. 校验PhpStorm调试端口 #

打开PhpStorm设置（快捷键Cmd+,），进入语言与框架 > PHP > 调试，确认Xdebug区域的调试端口为9001，与php.ini中xdebug.client_port值完全一致。

2. 检查端口占用情况 #

在终端执行命令，查看9001端口是否被其他进程占用：

lsof -i :9001

若有占用进程，执行以下命令终止进程（替换<PID>为查到的进程ID）：

kill -9 <PID>

3. 开启Xdebug日志排查细节 #

将php.ini中的xdebug.log_level从0修改为3，重启PHP服务后，在终端直接运行Pest测试：

./vendor/bin/pest

查看终端输出的Xdebug日志，日志会明确显示连接失败的具体原因（比如端口不通、IDE Key不匹配等）。

4. 确认IDE Key一致性 #

进入PhpStorm设置语言与框架 > PHP > 调试 > DBGp代理，检查IDE key是否为PHPSTORM，与php.ini中xdebug.idekey保持一致。

5. 测试Xdebug基础连接 #

在项目根目录创建测试文件test_xdebug.php：

<?php
phpinfo();

运行该文件后，在页面中搜索Xdebug，确认以下配置正确：

• xdebug.mode包含debug
• xdebug.client_port为9001
• xdebug.client_host为127.0.0.1

同时尝试在终端直接运行带调试参数的Pest测试：

./vendor/bin/pest -dxdebug.mode=debug

观察是否能触发PhpStorm的调试连接。

6. 排除防火墙/代理干扰 #

暂时关闭macOS防火墙（系统设置 > 网络 > 防火墙），同时关闭Charles、Fiddler等代理软件，再次尝试调试，确认是否是拦截导致的连接失败。

内容的提问来源于stack exchange，提问作者Daniel Haven