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，通过日志判断连接目标与握手过程是否成功。