【保姆级教程】Mac+Docker+Phpstrom+Xdebug

一. 环境介绍

MacOS Moiave 10.14

PHPSTROM 2017.3.6

Docker 2.2.0.5

PHP 5.6.4.0（php安装在docker容器中）

Xdebug 2.5.5

二. 安装&配置

（一）、Xdebug安装

网上关于安装的教程通常都是有一个命令带过；无奈我的环境一个命令搞不定（个中曲折难以解释），用网上常用的方法，将打印出来的phpinfo复制后粘贴https://xdebug.org/wizard.php查，得出来的结果居然是不支持，正常是会出现对应支持的版本供下载的。既然我的匹配不到，只能另谋它路了，找到了这个https://xdebug.org/docs/compat#versions 可以结合自己的php版本匹配对应的区间：

image.png

最后选择了2.5的版本，并在这个历史库里下载 https://xdebug.org/download/historical。
接下来就是怎么把包整到docker里面了：

直接 rz 把包上传d到 /usr/src/php/ext；
再解压tar -xf  xdebug-2.5.5.tgz；
最后执行安装：docker-php-ext-install xdebug-2.5.5

image.png

安装完成后，会在 /usr/local/etc/php/conf.d 生成对应的配置文件，扩展目录也会有对应的扩展文件 xdebug.so ：

image.png

至此，安装完毕，查看phpinfo可以看到多了xdebug扩展。

PS:
如果 rz、sz命令找不到：
执行命令：apt-get update && apt-get install lrzsz （docker中很多工具都没有，需要自己根据需要装进去）

（二）、Xdebug配置

我的配置：
zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20131226/xdebug.so
xdebug.idekey = PHPSTROM
xdebug.remote_host = host.docker.internal
xdebug.remote_connect_back = 0
xdebug.remote_enable = 1
xdebug.remote_port = 9001
xdebug.remote_handler = dbgp
xdebug.auto_trace = 1
xdebug.remote_mode = req
xdebug.remote_autostart = 1
xdebug.remote_log = /tmp/xdebug.log  

关键配置说明：

xdebug.remote_connect_back = 1
；//如果开启此，将忽略 xdebug.remote_host 的参数
；xdebug.remote_host=192.168.x.x
; //客户端的ip<即IDE的机器的ip,不是你的web server>
; //如果不希望固定IP经常要改，可以用如下两行，自动获取主机的地址
; xdebug.remote_host = host.docker.internal
; xdebug.remote_connect_back = 0
xdebug.remote_port = 9001
;//注意这里是，客户端的端口
xdebug.remote_log = /tmp/xdebug.log
;//日志一定要写，不然遇到问题一脸闷逼！！！

PS:
其中我还遇到了一个比较坑的问题：
1、docker里面ping不通本地的IP，容器内部网络问题，后面把docker客户端重启了就可以了。
2、日志文件没生成，有问题也一头雾水，后面改了下日志目录（也有可能是第一个网络问题造成的），重启容器就正常了。

（三）、PHPSTROM配置

1、为了让IDE也能用到xdebug，这里的配置非常重要，必须选用远程docker中的php版本：

① Phpstrom > prefernents > Languages & Frameworks > PHP，点击CLI interpreter右侧的...按钮，如下：

image.png

② 在弹出的CLI解析器对话框中点+号，选择“From Docker, Vagrant, VM, Remote...”。

image.png

③ 接着单选框选择 Docker，此时 Server应该是空的，点New...创建一个Docker连接。

image.png

④ Docker名称随便填，默认是Docker，然后选择连接Docker的方式，MAC选Docker for Mac.

image.png

⑤ 回到如下的界面，从下拉列表中选择PHP镜像，点OK确定。

image.png

⑥ 最后的效果如下：

image.png

2、配置debug端口（需要和前面xdeubg的一致）

image.png

image.png

3、配置server

image.png

4、配置调试选项

image.png

5、开始debug

点击下图右边红框中的小按钮，打开 Xdebug 监听，再选择我们要调试的目标，最后点击那个调试按钮，就能开启调试之旅。
点击左下角的可以一步步调试，看看都用到了什么。

image.png

三. Xdebug工作原理

1. IDE（如PhpStorm）已经集成了一个遵循BGDP的Xdebug插件，当开启它的时候， 会在本地开一个Xdebug调试服务，监听在调试器中所设置的端口上，默认是9000，这个服务就会监听所有到9000端口的链接。在PhpStorm中，位于：工具栏 > Run > Start / Stop Listening for PHP Xdebug Connetions。

2. 当浏览器发送一个带 XDEBUG_SESSION_START 的参数的请求到服务器时，服务器接受后将其转到后端的php处理，如果php开启了xdebug模块，则会将debug信息转发到客户端IP的IDE的调试端口上。当参数或者cookie信息中不带 XDEBUG_SESSION_START ，则不会启动调试。这就为后续在浏览器中添加开关提供了可能。Xdebug的官方给出了一个示例图：很好的展示了相互调用关系。 这个示例图是绑定了ip，即使用了固定ip地址，xdebug.remote_connect_back = 0 ，也是 Xdebug 的默认方式，这种情况下，Xdebug 在收到调试通知时会读取配置 xdebug.remote_host 和 xdebug.remote_port ，默认是 localhost:9000，然后向这个端口发送通知，这种方式只适合单一客户端开发调试。

   image.png
   另外一种方式则是不绑定IP，Xdebug根据请求来源（REMOTE_HOST）来发起调试。示例图如下：
   image.png

那从用户发起请求到，到IDE的整个流程图如下：

image.png

当用户的请求参数或者cookie中不带调试信息，数据流就是浏览器到Apache（或其他web容器）到PHP，如果加上了调试参数，则请求还会由PHP转给Xdebug处理，Xdebug再把信息转发给IDE，完成调试功能。

四. 遇到了哪些坑

1、9000端口占用（这个改下配置的端口就行了）

2、Waiting for incoming connection with ide key XXX
配置完一系列后，发现不管怎么debug都是这个提示语（一开始没用docker里的php，配置remote_host用了127.0.0.1）
上网查了一堆教程，有的说是xdebug版本不对，有的说是防火墙问题。
一波xdebug更换版本重装后发现还是不行，又是一波百度谷歌，发现phpstrom用的php需要和远程保持一致，于是乎改成用docker里的，这下总可以了吧。
事实证明想太多，还是不行。这个时候想起看下日志，发现居然日志都没写（有配置，但实际没日志）。一脸疑惑，配置了为什么没写日志呢，没日志怎么知道是什么问题，感觉有点没救了。
再后来看了下原理，关于通信的问题，发现容器居然跟本地不通。项目能直接访问，网络居然不通，又是一个疑惑，也是一通搜索，重启了docker之后，网络正常了。接下来想看看日志还是没，修改了下配置的路径，再试了debug，发现日志有了。更大的概率应该是网络解决了这个问题。
接着开始出现访问很卡的问题，然后隔一阵子就504了，好在知道是nignx超时，改了下：fastcgi_read_timeout 超时时间，之后debug就正常了。其他一些小问题已经不是很记得了，都是看日志搜问题解决的。这其中我也试过关掉本地的防火墙，最后调通，开启防火墙，发现能正常用，跟防火墙没什么关系。

PS：参考文献

（排名不分先后，别问我为什么那么多链接，因为一堆莫名其妙的问题，建议大家接合自身情况多看看）

https://www.jianshu.com/p/767ffd64b339

https://www.php.cn/docker/445875.html

https://blog.csdn.net/z457181562/article/details/94719817

https://paper.seebug.org/308/

https://segmentfault.com/a/1190000017482138

https://www.jianshu.com/p/c99867e8e49c

Waiting for incoming connection with ide key 的各种答案，仅供参考，重点还是看日志

https://segmentfault.com/q/1010000004027601

https://blog.csdn.net/zhenglu008/article/details/77493660

远程使用docker环境的 教程参考

https://www.awaimai.com/2733.html#comment-36462