VSCode XDebug 远程调试虚拟机CentOS7上PHP项目

声明

以下[参考]链接，如有侵权，请联系删除，在此先感谢在网络上无私奉献的人们~

如有错误，请联系更正

背景

本机环境：Win10，已安装VSCode与PHP Debug插件，项目代码存放端（也可放在远程机上），用于调试代码

远程机：CentOS7（本机VMWare创建），已部署PHP、XDebug与Nginx，用于PHP项目发布

本文目的：开发环境在远程机，只要实现本机与远程机的代码同步（由于本文所述远程机为本机上的虚拟机，因此用文件夹共享的方式实现“同步”），即可在本机没有部署PHP环境的情况下远程调试代码

本机配置

1. 安装VSCode
2. 在VSCode上安装PHP Debug插件
3. 假设代码放在本机 D:/path/to/project/dir，用VSCode打开项目地址，添加PHP调试配置 launch.json，增加以下内容

{
    "name": "Remote for XDebug",
    "type": "php",
    "request": "launch",
    "pathMappings": {
        // "远程机上代码地址（本文为虚拟机共享文件地址）": "本机代码地址"
        "/mnt/hgfs/path/to/project/dir": "${workspaceRoot}"
    },
    "port": 9001  // 注意：为避免端口冲突，设置为9001（后文会解释）
},

虚拟机配置

1. 设置代码文件共享

在虚拟机关机状态下配置共享文件夹

一般开机后能在 mnt/hgfs 下看到挂在的共享文件夹 mnt/hgfs/path/to/project/dir，如果该文件夹为空，作如下处理：

• 先确认虚拟机已安装 vmware-tools

• 创建挂载共享文件的脚本（CentOS7用vmhgfs-fuse不能实现永久挂载，可以写成服务，设置开机启动）

  sudo mkdir /usr/local/scripts    # 自定义脚本存放目录
  sudo gedit /usr/local/scripts/hgfs.sh    # 挂载目录的脚本
  

  在 hgfs.sh 中插入以下内容并保存（注意：以下 uid gid 对应当前启动用户，可用命令 id -u id -g 查看，一定要设置，否则会引发一系列权限问题，一定要将php、nginx的进程用户以及本文涉及的用户设置都统一）

  #!/bin/sh
  /usr/bin/vmhgfs-fuse .host:/ /mnt/hgfs -o uid=1000 -o gid=1000 -o subtype=vmhgfs-fuse,allow_other
  

• 创建并启动服务

  sudo chmod +x /usr/local/scripts/hgfs.sh     # 给脚本赋予执行权限，否则服务无法启动
  sudo gedit /etc/systemd/system/hgfs.service    # 创建服务
  

  在 hgfs.service 中插入以下内容并保存

  [Unit]
  Description=hgfs
  ConditionVirtualization=vmware
  Requires=vgauthd.service
  After=vgauthd.service vmtoolsd.service
  
  [Service]
  Type=forking
  ExecStart=/usr/local/scripts/hgfs.sh
  ExecReload=/usr/local/scripts/hgfs.sh
  ExecStop=
  TimeoutStopSec=5
  
  [Install]
  WantedBy=multi-user.target
  Also=vgauthd.service vmtoolsd.service
  

  启动服务

  systemctl start hgfs     # 启动服务
  systemctl enable hgfs    # 开机启动
  

• 将该共享位置发布到Nginx，发布方式可参考之前发过的文章：CentOS7+PHP7+Apache+Nginx环境配置与多站点部署

2. 修改xdebug配置

找到配置文件 /etc/php.d/xdebug.ini，插入已下内容（如果没有该文件，可直接把以下内容插入到 /etc/php.ini底部）
注意：考虑到Nginx会占用9000端口，因此将xdebug远程端口设置为9001

zend_extension=/usr/lib64/php/modules/xdebug.so
[XDebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_port = 9001
xdebug.remote_connect_back = 1
xdebug.auto_trace = 1
xdebug.collect_includes = 1
xdebug.collect_params = 1
xdebug.remote_log = /var/log/xdebug.log

创建 xdebug.log 并赋权限

sudo gedit /var/log/xdebug.log    # 文件弹出后直接保存退出
sudo chown currentuser:currentuser /tmp/xdebug-remote.log    # 将currentuser换成当前启动用户的名字
sudo chmod 666 /var/log/xdebug.log
systemctl restart php-fpm    # 重启php服务

3. 修改 SELinux 参数

sudo setsebool -P httpd_can_network_connect_db 1
sudo setsebool -P httpd_can_network_connect 1
sudo setsebool -P httpd_read_user_content 1
sudo chcon -R -h -t httpd_sys_content_t /path/to/project/a/dir  # 只读权限
sudo chcon -R -h -t httpd_log_t /path/to/project/a/dir/log  # 附加内容的权限（择需处理）
sudo chcon -R -h -t httpd_sys_script_rw_t /path/to/project/a/dir/upload  # 读写权限（择需处理）

4. 调试

先确保能在本机浏览器上访问远程机部署的项目地址，如不能访问可查看nginx错误日志 /var/log/nginx/error.log，根据提示修正。

在本机VSCode启动之前新建的调试配置 Remote for XDebug，刷新本机浏览器所访问的远程机部署的项目页面，即可进行调试。

注意：如果不能进入断点，先判断断点位置是否正确，在查看远程机上xdebug日志 /var/log/xdebug.log，根据提示修正。

防止调试超时

在断点时间过长的情况下页面容易出现 504 Gateway Timeout 的超时错误，需要对以下三个文件做相应配置

• PHP配置：在 /etc/php.ini 中修改最长执行时间 max_execution_time = 3600 （默认单位为秒）
• PHP-FPM配置：在 /etc/php-fpm.d/www.conf 中修改请求终止超时时间 request_terminate_timeout = 3600（默认单位为秒）
• Nginx配置：在 /etc/nginx/nginx.conf 中 http 内增加请求终止超时时间 fastcgi_read_timeout 3600;（默认单位为秒）
• 重启 php-fpm 和 nginx 服务

参考

1. centos7 vmtools 设置共享目录 - 鬼方赤命的个人页面 - OSCHINA
2. Centos 7 共享文件夹hgfs没内容 &文件夹永久共享 - 台部落
3. vscode+XDebug调试远程环境(虚拟机)上的PHP代码_郑晓_个人博客
4. XDebug could not open the remote debug file ‘/tmp/xdebug-remote.log’. · Issue #621 · Varying-Vagrant-Vagrants/VVV
5. Nginx, php-fpm and SELinux enforcing on CentOS 7 - oBlog
6. CentOS 7 + SELinux + PHP + Apache – cannot write/access file no matter what | Lysender’s Daily Log Book
7. 504 Gateway Timeout error on Nginx + FastCGI (php-fpm) | Blog of Leonid Mamchenkov