需配置 Xdebug 远程连接、PhpStorm 监听端口 9003、路径映射及浏览器插件触发；步骤包括：一、远程服务器启用 Xdebug 并设 client_host 为本地 IP；二、PhpStorm 配置远程 PHP 解释器与调试端口；三、设置服务器配置及路径映射；四、启动监听并用 URL 参数或插件触发调试会话。
如果您在本地使用 PhpStorm 开发 PHP 应用，但需要实时调试部署在远程服务器上的代码，则必须建立可靠的远程调试通道。以下是完成 PhpStorm 远程调试配置与连接的具体操作步骤：
一、配置远程服务器的 Xdebug 扩展
Xdebug 是实现远程调试的核心扩展，需确保其已正确安装并启用，且参数适配 PhpStorm 的监听要求。关键在于使远程服务器能主动向本地 PhpStorm 发起调试连接请求。
1、通过 SSH 登录远程服务器，定位 php.ini 文件路径（通常为 /etc/php/*/apache2/php.ini 或 /etc/php/*/cli/php.ini）。
2、在 php.ini 文件末尾添加或修改以下 Xdebug 配置项：
立即学习 “PHP 免费学习笔记（深入）”；
xdebug.mode=debug
xdebug.client_host= 您的本地电脑公网 IP 或路由器映射后的内网 IP
xdebug.client_port=9003
xdebug.connect_timeout_ms=2000
xdebug.log=/var/log/xdebug.log
3、保存 php.ini 后重启 Web 服务（如 Apache：sudo systemctl restart apache2；或 Nginx + PHP-FPM：sudo systemctl restart php*-fpm nginx）。
4、在远程服务器执行 php -m | grep xdebug，确认模块已加载；再运行 php -i | grep “xdebug.mode” 和 “xdebug.client_host”，验证配置生效。
二、在 PhpStorm 中设置 PHP 解释器与调试端口
PhpStorm 需识别远程 PHP 环境并监听指定端口，以接收来自 Xdebug 的调试会话请求。此步骤建立本地调试入口点。
1、打开 PhpStorm，进入 File → Settings（Windows/Linux）或 PhpStorm → Preferences（macOS）。
2、导航至 Languages & Frameworks → PHP，点击右侧解释器旁的“……”按钮。
3、点击“+”号，选择“From Docker, Vagrant, VM, Remote……”选项。
4、在弹出窗口中选择“Remote CLI Configuration”，点击 Next。
5、配置连接类型为“SFTP”，填写远程服务器的主机地址、端口、用户名及认证方式（密码或密钥文件）。
6、在“PHP executable”字段中输入远程服务器上 PHP 的绝对路径（如 /usr/bin/php），点击“Load Configuration”自动获取版本与扩展信息。
7、返回 Settings 主界面，进入 Languages & Frameworks → PHP → Debug，将“Debug port”设置为 9003，勾选“Can accept external connections”。
三、配置服务器配置（Server Configuration）与路径映射
PhpStorm 必须将远程服务器上的文件路径准确映射到本地项目目录，否则断点无法命中。该映射是调试上下文对齐的基础。
1、进入 Run → Edit Configurations……，点击左上角“+”号，选择“PHP Web Page”。
2、在“Server configuration”下拉菜单中，点击“……”打开服务器配置窗口。
3、点击“+”添加新服务器，填写名称（如 production-server），主机地址（如 example.com），端口（如 80 或 443）。
4、在“Debugger”区域，选择“Xdebug”，并确认端口为 9003。
5、展开“Use path mappings”，点击右侧“……”按钮，在“Remote path”栏输入远程网站根目录（如 /var/www/html），在“Local path”栏选择本地对应项目根目录。
6、若存在多级子目录或部署路径嵌套，逐行添加其余映射关系，确保所有含断点的 PHP 文件路径均被覆盖。
四、启动调试会话并触发断点
完成环境配置后，需主动发起一次携带调试参数的 HTTP 请求，促使 Xdebug 向 PhpStorm 发送连接请求。此时 PhpStorm 将捕获会话并停在预设断点处。
1、在本地 PhpStorm 的 PHP 文件中，点击行号左侧灰色区域设置断点（出现红点即表示激活）。
2、点击右上角电话图标旁的“Start Listening for PHP Debug Connections”按钮（绿色小电话图标），启用监听。
3、在浏览器中访问远程 URL，并在查询参数中追加 ?XDEBUG_SESSION_START=PHPSTORM（如 https://example.com/index.php?XDEBUG_SESSION_START=PHPSTORM）。
4、若未自动弹出“Incoming Connection from Xdebug”提示框，检查 PhpStorm 右下角是否显示“Debug listening……”以及状态栏是否有 Xdebug 图标亮起。
5、当页面加载暂停时，查看 PhpStorm 的“Variables”、“Watches”、“Frames”等调试面板，确认变量值与执行栈正常显示。
五、使用 Xdebug Helper 浏览器插件简化触发流程
手动拼接 URL 参数易出错且效率低，借助浏览器插件可一键发送调试令牌，避免遗漏或拼写错误，提升调试启动一致性。
1、在 Chrome 或 Firefox 中安装官方 Xdebug Helper 插件（作者：Joel Clermont）。
2、点击浏览器工具栏中的虫子图标，选择“Debug”模式，确保状态显示为绿色“Debug enabled”。
3、进入 PhpStorm，打开 Settings → PHP → Servers，确认已配置对应域名且“Use path mappings”已启用。
4、访问远程站点任意页面，插件将自动在请求头中注入 X-Forwarded-For 和 Cookie：XDEBUG_SESSION=PHPSTORM。
5、PhpStorm 接收到请求后，若路径映射正确且监听开启，将立即中断于首个有效断点，无需修改 URL。
