PhpStorm连接远程Web服务器时Xdebug调试不生效该如何解决？

1. 确认Xdebug核心配置匹配Xdebug 3版本规范 #

Xdebug 3和旧版2.x参数差异极大，必须用3.x专属参数，检查php.ini中以下配置：

• xdebug.mode 必须设置为 debug，仅配置develop模式无法触发断点调试
• xdebug.client_host 填写运行PhpStorm的本地设备公网IP（托管主机为远程服务，需要主动连接你本地的调试端口，不能填127.0.0.1或者服务器IP）
• xdebug.client_port 默认值为9003，不要和php-fpm默认的9000端口混淆
• 临时调试可设置xdebug.start_with_request = yes跳过触发条件校验，排查完再改回trigger配合浏览器扩展使用
• 新增xdebug.log = /tmp/xdebug.log配置，日志会记录所有连接错误，是排查核心依据

2. 校验PhpStorm配置一致性 #

• 打开File > Settings > PHP > Debug，确认Xdebug端口和上述xdebug.client_port完全一致
• 打开File > Settings > PHP > Servers，选中你配置的托管主机，必须配置路径映射：将服务器上代码的绝对路径，和你本地PhpStorm打开的同一份代码的绝对路径一一对应，路径映射错误是断点不触发的高频原因
• 确认PhpStorm左上角的调试监听按钮已开启，状态为绿色播放图标

3. 网络连通性校验 #

如果xdebug日志中出现connect to client[xxx.xxx.xxx.xxx:9003] failed: Connection refused报错，说明托管主机无法连接你本地的调试端口：

• 检查本地设备防火墙是否开放了对应调试端口的入站规则
• 如果你本地处于内网环境，需要做内网穿透将调试端口映射到公网，确保托管主机可以访问到该端口
• 不要使用VPN等会篡改本地IP的工具，避免xdebug.client_host配置的IP和实际公网IP不一致

4. 浏览器扩展校验 #

基础调试通了之后再配置Xdebug helper扩展：

• 右键扩展图标打开选项页，IDE key选择PhpStorm，保存配置
• 访问目标站点时，点击扩展图标选择Debug模式，确认地址栏扩展图标变为绿色
• 确认站点的扩展权限已开启，https站点需要授予扩展在https页面运行的权限

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