Warden环境下PhpStorm调试器无法连接Xdebug求助

1. 确认容器内Xdebug版本与核心配置 #

先进入php-debug容器，直接查看Xdebug的版本和运行时配置：

# 查看Xdebug版本
warden shell php-debug -c 'php -v'

# 查看完整Xdebug配置
warden shell php-debug -c 'php -i | grep -A25 Xdebug'

• 若为Xdebug 2，重点检查：
  • xdebug.remote_enable = On
  • xdebug.remote_host 应为宿主机IP或host.docker.internal（避免用127.0.0.1，容器内指向自身）
  • xdebug.remote_port = 9000
  • xdebug.idekey = PHPSTORM
• 若为Xdebug 3，对应检查：
  • xdebug.mode = debug
  • xdebug.client_host 同上，指向宿主机
  • xdebug.client_port = 9003
  • xdebug.idekey = PHPSTORM
  • xdebug.start_with_request = trigger（需浏览器触发调试会话）

2. 验证宿主机端口监听与容器连通性 #

• 先确认PhpStorm在监听对应端口：

  # Xdebug 2
  lsof -i :9000
  
  # Xdebug 3
  lsof -i :9003
  

  输出应显示phpstorm进程在监听该端口。

• 进入php-debug容器测试与宿主机端口的连通性：

  # 替换成你的宿主机局域网IP，比如192.168.1.100
  telnet 192.168.1.100 9000
  # 或Xdebug3用9003
  telnet 192.168.1.100 9003
  

  若提示Connection refused，检查宿主机防火墙是否放行该端口，或Warden网络是否存在隔离。

3. 核对PhpStorm路径映射是否完全匹配 #

PhpStorm的服务器配置中，本地项目根目录必须精确对应容器内的/var/www/html，层级不能错：

• 比如本地路径/Users/xxx/magento1/app/code/local/Custom，必须映射到容器内/var/www/html/app/code/local/Custom
• 可通过右键PhpStorm中的文件→Copy Path/Reference获取本地路径，再在容器内用ls /var/www/html/对应路径验证文件存在

4. 确认浏览器调试触发状态 #

• 确保Xdebug浏览器扩展（如Xdebug Helper）的IDE密钥设为PHPSTORM，且当前页面处于调试启用状态（图标变绿）
• 打开浏览器开发者工具→Cookie，确认存在XDEBUG_SESSION=PHPSTORM的Cookie；若没有，手动添加后刷新页面测试

5. 启用Xdebug日志定位具体错误 #

在容器的php.ini中添加日志配置（或通过Warden环境变量设置）：

# Xdebug2
xdebug.log=/var/log/xdebug.log
xdebug.log_level=7

# Xdebug3
xdebug.log=/var/log/xdebug.log
xdebug.log_level=7

然后刷新页面，查看日志内容：

warden shell php-debug -c 'cat /var/log/xdebug.log'

日志会直接显示连接失败原因（如无法解析主机、端口不通、IDE密钥不匹配等）。

6. 检查Warden环境变量配置 #

查看项目根目录的.env文件：

• 确保WARDEN_PHP_DEBUG=1（启用调试容器）
• 确认没有自定义XDEBUG_CONFIG或XDEBUG_MODE覆盖默认配置（比如XDEBUG_MODE=off会直接禁用调试）

7. 核对PhpStorm调试配置细节 #

• 远程调试配置中，Server必须选择你创建的sa1-docker
• 调试端口需与Xdebug配置完全一致（9000或9003）
• 确保右上角的Listen for PHP Debug Connections按钮处于激活状态（电话图标亮起）

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