XDebug调试连接失败问题排查求助

根据描述，迁移服务器后XDebug已加载但无法建立调试连接，可按以下步骤逐一排查：

1. 验证SSH端口转发配置的有效性 #

由于服务器仅支持SSH访问，XDebug需通过端口转发连接本地PHPStorm：

• 检查PuTTY的反向端口转发配置：需设置Remote port: 9003，Destination: localhost:9003，确保规则已启用且PuTTY连接处于活跃状态
• 在服务器上执行命令测试连通性：telnet localhost 9003，若连接失败，说明端口转发未正确配置

2. 修正XDebug配置文件的问题 #

配置文件存在两处潜在问题：

• 移除末尾无效的#[/xdebug]#标记（INI文件仅支持;作为注释符，该标记可能干扰配置解析）
• 取消注释xdebug.client_host = 127.0.0.1，明确指定连接IPv4回环地址，避免localhost解析到IPv6导致端口转发不匹配

修改后的配置片段：

[xdebug]
zend_extension = /usr/lib/php/20210902/xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_port = 9003
xdebug.client_host = 127.0.0.1
xdebug.log = "/var/log/xdebug.log"
xdebug.idekey = PHPSTORM

3. 确保PHP-FPM已重载配置 #

修改XDebug配置后必须重启PHP-FPM才能生效：

sudo systemctl restart php8.1-fpm

重启后通过xdebug_info()或phpinfo()确认配置已正确加载

4. 检查本地机器的防火墙/杀毒软件 #

本地防火墙或杀毒软件可能拦截了9003端口的入站连接：

• 暂时关闭防火墙或添加入站规则，允许9003端口的TCP流量
• 测试调试连接是否恢复

5. 排查端口占用问题 #

若9003端口被其他进程占用，可更换端口测试：

• 修改XDebug配置的xdebug.client_port为其他值（如9004）
• 更新PuTTY的端口转发规则和PHPStorm的监听端口为对应值
• 重启PHP-FPM后再次测试

6. 开启XDebug详细日志定位问题 #

添加xdebug.log_level = 7到XDebug配置，开启最详细的日志输出：

xdebug.log_level = 7

重启PHP-FPM后触发调试，查看/var/log/xdebug.log中的详细错误信息，可进一步定位连接失败的原因（如DNS解析、权限限制等）

7. 验证PHPStorm的监听配置 #

• 确认PHPStorm右上角的Start Listening for PHP Debug Connections按钮已激活（电话图标亮起）
• 检查PHPStorm设置Languages & Frameworks > PHP > Debug中，XDebug的端口与配置一致
• 在本地机器执行命令检查端口占用：
  • Windows：netstat -ano | findstr :9003
  • Mac/Linux：lsof -i :9003
    确保无其他进程占用该端口

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