Ubuntu上PHPStorm如何进行远程调试

Ubuntu上PHPStorm远程调试实操指南

一 场景与原理

• 常见场景包括：在本地 Ubuntu 上用 PHPStorm 调试运行在另一台服务器（或本机虚拟机/Docker）中的 PHP 代码。关键在于让远程 PHP 的 Xdebug 能够连接到 PHPStorm 的调试端口（默认 9003），双方用 DBGp 协议通信。若远程服务器无法直连你的开发机，需借助 SSH 端口转发 打通通道。

二 方案一 远程服务器可直连开发机时的配置

• 远程服务器安装 Xdebug（Ubuntu/Debian 示例）
  • 安装扩展：sudo apt-get update & & sudo apt-get install php-xdebug
  • 编辑对应 SAPI 的 php.ini（如 /etc/php/8.1/fpm/php.ini 或 /etc/php/8.1/apache2/php.ini），在末尾加入：
    • [xdebug]
    • zend_extension=xdebug.so
    • xdebug.mode=debug
    • xdebug.client_host=你的开发机IP（如 192.168.1.100）
    • xdebug.client_port=9003
    • xdebug.start_with_request=yes
    • xdebug.idekey=PHPSTORM
  • 重启服务：sudo systemctl restart apache2 或 sudo systemctl restart php8.1-fpm & & sudo systemctl restart nginx
• PHPStorm 设置
  • File → Settings → Languages & Frameworks → PHP → Servers：新增服务器，填写远程 Host/Port，Debugger 选 Xdebug；若本地与远程代码路径不同，配置 Path mappings（本地项目根目录 ↔ 服务器项目根目录）。
  • File → Settings → Languages & Frameworks → PHP → Debug：确认 Debug port=9003。
  • Run → Edit Configurations → 新建 PHP Remote Debug：选择上一步的 Server，IDE key 填 PHPSTORM，Debugger mode 选 Attach to remote host。
• 开始调试
  • 在 PHPStorm 点击 “电话”图标开始监听；浏览器访问目标 URL，必要时在 URL 上附加参数：?XDEBUG_SESSION_START=PHPSTORM，命中断点后即可单步、查看变量与调用栈。

三 方案二 远程服务器无法直连开发机时的 SSH 隧道

• 思路：让远程服务器的 9003 端口通过 SSH 转发到本地开发机的 9003，这样 Xdebug 连接的是“本机”的 PHPStorm。
• 建立隧道（在本地开发机执行）
  • 标准端口转发：ssh -R 9003:localhost:9003 user@远程服务器IP
  • 若远程是云主机且只开放跳板机端口，可先连跳板机再转发：ssh -J jumpuser@跳板机IP -R 9003:localhost:9003 user@目标服务器IP
• 远程服务器 Xdebug 配置
  • xdebug.client_host=127.0.0.1（隧道已把 9003 映射到本机）
  • xdebug.client_port=9003
  • 其他保持与方案一一致（mode=debug、idekey=PHPSTORM 等）
• PHPStorm 设置
  • Servers 与 Debug 端口按方案一配置；Run/Debug Configurations 使用 PHP Remote Debug 并启动监听，访问远程 URL 触发调试。
• 验证隧道
  • 在远程服务器上执行：telnet 127.0.0.1 9003，能连通说明隧道与 Xdebug 端口正常。

四 常见问题与排查

• 端口与连通性
  • 确认远程 php.ini 的 xdebug.client_port 与 PHPStorm 的 Debug port 一致（推荐 9003）；服务器与网络侧防火墙需放行该端口（或仅放行 SSH 用于隧道）。
• IDE 无法捕获请求
  • 核对 Servers → Path mappings 是否正确；确保请求携带 XDEBUG_SESSION_START=PHPSTORM 或使用 Xdebug Helper 浏览器插件触发调试；PHPStorm 处于“监听”状态。
• 版本与配置项差异
  • Xdebug 3 使用 xdebug.mode=debug、xdebug.client_host、xdebug.client_port；Xdebug 2 使用 remote_enable、remote_host、remote_port 等，混用会导致不生效。
• 日志定位
  • 在远程 php.ini 增加：xdebug.log=/tmp/xdebug.log，通过日志判断连接目标与握手过程是否成功。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！