Laradock+PhpStorm+Xdebug调试失败但PhpStorm验证通过

我之前在Docker 17.x + macOS Sierra的环境里碰到过几乎一模一样的Xdebug调试无响应问题，给你几个针对性的排查和解决步骤，应该能帮你搞定：

1. 修正Xdebug容器配置（核心！） #

PhpStorm的验证通过只是基础，但Docker环境下Xdebug需要主动连接宿主机，所以一定要确保容器内的Xdebug配置适配网络：

• 找到容器内的Xdebug配置文件（通常是/usr/local/etc/php/conf.d/xdebug.ini或者php.ini里的Xdebug段），修改为：

  xdebug.remote_enable = 1
  xdebug.remote_autostart = 1  # 开启自动启动，避免插件触发失败的问题
  xdebug.remote_connect_back = 0  # 关闭自动回连，Docker环境下这个会导致连接错误
  xdebug.remote_host = 你的宿主机真实IP  # 比如用终端执行`ifconfig en0`拿到的192.168.x.x
  xdebug.remote_port = 9000  # 和PhpStorm监听端口保持一致
  xdebug.idekey = PHPSTORM
  xdebug.remote_log = /tmp/xdebug.log  # 开启日志，方便排查问题
  

  注意：Docker 17.02还不支持docker.for.mac.internal.host，这个是Docker for Mac后续版本才引入的宿主机别名，所以用它会导致容器启动失败，直接用宿主机真实IP就好。

2. 检查PhpStorm的关键配置 #

• 打开「Preferences > Languages & Frameworks > PHP > Debug」，确认Xdebug的「Debug port」是9000，并且勾选「Can accept external connections」
• 进入「Preferences > Languages & Frameworks > PHP > Servers」：
  • 服务器的「Host」要和你浏览器访问的地址完全一致（比如localhost或者你的测试域名）
  • 务必勾选「Use path mappings」，把本地项目根目录（比如/Users/xxx/my-project）映射到容器内的项目路径（比如/var/www/html），路径映射错误是断点不触发的常见原因！

3. 验证网络连通性 #

• 进入Docker容器（docker exec -it 容器名 bash），执行telnet 宿主机IP 9000，如果能成功连接，说明网络没问题；如果连接失败，检查Mac的防火墙是否阻止了9000端口，或者PhpStorm是否被允许接收传入连接（在系统偏好设置的安全与隐私里确认）
• 查看Xdebug日志：刷新页面后，去容器内的/tmp/xdebug.log看日志内容，里面会明确显示连接失败的原因（比如端口不通、idekey不匹配等）

4. 插件与手动触发调试 #

• 确认Chrome的Xdebug Helper插件的「IDE Key」设置为PHPSTORM，并且点击插件图标激活（图标变绿色）
• 如果插件没效果，手动在URL末尾加?XDEBUG_SESSION_START=PHPSTORM再刷新页面，强制触发调试会话

5. 排查端口占用 #

用Mac终端执行lsof -i :9000，看看有没有其他进程占用了9000端口，如果有，把PhpStorm和Xdebug的端口改成其他值（比如9001），重启PhpStorm和容器后再试。

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