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

最新推荐文章于 2025-11-11 22:27:40 发布

原创最新推荐文章于 2025-11-11 22:27:40 发布 · 3.2k 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#vscode #xdebug #php #虚拟机 #centos7

本文详细介绍如何在Win10环境下使用VSCode与PHPDebug插件，通过虚拟机共享文件夹实现在本机调试远程CentOS7上的PHP项目。涵盖配置步骤、XDebug设置、SELinux调整及解决调试超时问题。

声明

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

如有错误，请联系更正

文章目录

背景

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

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

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

本机配置

安装VSCode
在VSCode上安装PHP Debug插件
假设代码放在本机 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. 设置代码文件共享

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

一般开机后能在 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，根据提示修正。

VSCode

防止调试超时

在断点时间过长的情况下页面容易出现 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 服务