需配置Xdebug远程调试：一、远程服务器安装启用Xdebug并设client_host为本地IP；二、VSCode安装PHP Debug插件并配置debug端口；三、launch.json中设置pathMappings映射路径；四、防火墙限制时用SSH端口转发；五、浏览器加?XDEBUG_SESSION_START=1触发断点。
如果您希望在本地使用 VSCode 对运行于远程服务器上的 PHP 应用进行断点调试，则需借助 Xdebug 或 Zend Debugger 与远程服务器建立通信连接。以下是完成该配置的具体操作步骤：
一、确认远程服务器已安装并启用 Xdebug
Xdebug 是 PHP 的扩展调试工具，必须在远程服务器的 PHP 环境中正确安装并启用，且其配置需支持远程调试请求转发至本地 VSCode。确保 PHP 版本与 Xdebug 版本兼容，并启用远程调试模式。
1、通过 SSH 登录远程服务器，执行 php -v 查看 PHP 版本。
2、执行 php -m | grep xdebug 检查 Xdebug 是否已加载。
立即学习“PHP免费学习笔记（深入）”；
3、若未安装，根据 PHP 版本下载对应 Xdebug 扩展（如使用 pecl：执行 pecl install xdebug）。
4、编辑 php.ini 文件（路径可通过 php --ini 获取），在末尾添加以下配置段：
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=您的本地IP地址
xdebug.client_port=9003
xdebug.log=/var/log/xdebug.log
二、在 VSCode 中安装并配置 PHP Debug 插件
VSCode 本身不内置 PHP 调试能力，需依赖 PHP Debug 扩展（由 Felix Becker 维护）来解析 Xdebug 协议并提供 UI 控制界面。该插件负责监听指定端口，接收来自远程服务器的调试连接请求。
1、打开 VSCode，进入扩展市场，搜索 PHP Debug 并点击安装。
2、安装完成后，按下 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Preferences: Open Settings (JSON) 并回车。
3、在 settings.json 中添加如下配置项（若无则新建）：
"php.debug.executablePath": "/usr/bin/php"
"php.debug.port": 9003
"php.debug.log": true
三、配置 VSCode 的 launch.json 启动调试任务
launch.json 定义了调试会话的参数，包括监听端口、路径映射关系、是否自动启动等。对于远程调试，关键在于设置正确的 pathMapping，使远程服务器文件路径与本地工作区路径一一对应，否则断点无法命中。
1、在项目根目录下打开命令面板，输入 Debug: Open launch.json，选择环境为 PHP。
2、替换生成的配置为以下内容（注意修改 pathMappings 中的路径）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
四、配置 SSH 端口转发（适用于防火墙限制场景）
当远程服务器的 9003 端口无法直接被本地机器访问（如云服务器安全组默认禁止入向非 HTTP/HTTPS 端口），可利用 SSH 本地端口转发将远程调试流量安全地代理至本地 VSCode 监听端口。
1、在本地终端执行以下命令（替换 user@remote_ip 为实际值）：
ssh -R 9003:127.0.0.1:9003 user@remote_ip
2、确保远程服务器上 Xdebug 配置中的 xdebug.client_host 改为 127.0.0.1。
3、保持该 SSH 连接处于活动状态，再启动 VSCode 调试会话。
五、验证调试连接并触发断点
调试会话启动后，VSCode 将监听指定端口等待 Xdebug 连接；此时需从浏览器或 CLI 触发目标 PHP 脚本，并携带 Xdebug 启用参数，使远程 PHP 进程主动连接本地调试器。
1、在 VSCode 中点击左侧调试图标，选择 Listen for Xdebug 配置，然后点击绿色三角形启动监听。
2、在浏览器中访问远程 URL，并在末尾附加查询参数：?XDEBUG_SESSION_START=1。
3、在本地 PHP 文件中任意行左侧灰色区域点击，设置断点（出现红色圆点）。
4、刷新浏览器页面，观察 VSCode 是否自动跳转至断点位置，并显示变量值、调用栈等调试信息。
