Ubuntu下 PhpStorm 远程调试 PHP 的完整步骤
一 环境准备与差异说明
- 常见两种场景：
- 本机是 Ubuntu，直接在本地安装 PHP + Xdebug + PhpStorm 进行调试（最简单）。
- 本机是 Ubuntu，调试 远程服务器（如云主机、内网服务器）上的 PHP 代码。
- 调试器使用 Xdebug 3.x（推荐），默认调试端口为 9003；老项目若用 Xdebug 2.x，端口常为 9000，且配置项不同。下文以 Xdebug 3 为主，并在文末给出 2.x 对照与 SSH 隧道方案。
二 本机 Ubuntu 环境快速配置（Xdebug 3）
- 安装 Xdebug
- 查看 PHP 版本：php -v
- 安装对应扩展（以 Ubuntu 20.04/22.04 常见版本为例）：sudo apt-get install php-xdebug
- 配置 php.ini（仅保留一个 [xdebug] 段，路径可能为：/etc/php/7.x/apache2/php.ini 或 /etc/php/7.x/cli/php.ini）
- 建议值：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003
- xdebug.start_with_request=yes
- xdebug.idekey=PHPSTORM
- 重启服务
- Apache：sudo systemctl restart apache2
- Nginx+PHP-FPM：sudo systemctl restart php7.x-fpm && sudo systemctl restart nginx
- PhpStorm 设置
- File → Settings → Languages & Frameworks → PHP → Debug：确保 Debug port 为 9003
- File → Settings → Languages & Frameworks → PHP → Servers：新增服务器
- Name：任意
- Host：localhost（或你的站点域名）
- Port：80/443
- Debugger：Xdebug
- 开始调试
- 在代码行号左侧点击设置断点
- 点击工具栏“电话听筒”图标开始监听
- 浏览器访问：http://localhost/your.php?XDEBUG_SESSION_START=PHPSTORM
- 命中断点后可使用 F7/F8/Shift+F8 等调试控制。
三 调试远程服务器上的 PHP（Ubuntu 本机 + 远程服务器）
- 远程服务器配置（Xdebug 3）
- 安装：sudo apt-get install php-xdebug
- 编辑远程 php.ini（路径因 SAPI 而异：/etc/php/7.x/apache2/php.ini 或 /etc/php/7.x/fpm/php.ini）
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=你的本机公网/内网 IP（服务器要能访问到你）
- xdebug.client_port=9003
- xdebug.start_with_request=yes
- xdebug.idekey=PHPSTORM
- 重启：sudo systemctl restart apache2 或 sudo systemctl restart php7.x-fpm && sudo systemctl restart nginx
- 网络与防火墙
- 确保服务器能访问你的 9003 端口（云主机需放通安全组/防火墙）
- 若服务器无法直连你的本机（常见于 NAT/公司网络），使用 SSH 隧道（见第四部分）
- PhpStorm 设置
- File → Settings → PHP → Servers：新增服务器
- Name：任意
- Host：远程服务器域名/IP
- Port：80/443
- Debugger：Xdebug
- Run → Edit Configurations → 新建 PHP Remote Debug
- Server：选择上面服务器
- IDE key：PHPSTORM
- 启动监听（电话听筒），浏览器访问远程 URL 并带上 XDEBUG_SESSION_START=PHPSTORM 触发调试。
四 网络受限时使用 SSH 隧道（服务器无法直连本机 9003）
- 建立隧道（在你本机 Ubuntu 终端执行）
- 将远程的 9003 转发到本机 9003：ssh -R 9003:localhost:9003 user@remote_host
- 远程 php.ini 调整
- 因隧道把请求转发到本机，client_host 改为：127.0.0.1
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003
- 启动顺序
- 保持 SSH 隧道连接
- PhpStorm 开启监听
- 浏览器访问远程站点并带上 XDEBUG_SESSION_START=PHPSTORM
- 验证隧道连通（在远程服务器上）
- telnet 127.0.0.1 9003 应可连通（用于排查端口转发是否成功）。
五 常见问题与排查要点
- 端口不一致
- 确认 php.ini 的 xdebug.client_port 与 PhpStorm → PHP → Debug 的 Debug port 一致（默认 9003）。
- 路由不通
- 服务器必须能访问你的 client_host:client_port；不通时优先用 SSH 隧道。
- 配置未生效
- 检查是否改对了 SAPI 的 php.ini（Apache 与 PHP-FPM 可能不同），修改后重启对应服务。
- 使用 Xdebug 2.x 的老项目（如看到 remote_enable 等参数）
- 典型配置示例：
- zend_extension=xdebug.so
- xdebug.remote_enable=1
- xdebug.remote_host=你的本机IP
- xdebug.remote_port=9000/9003
- xdebug.remote_handler=dbgp
- xdebug.remote_mode=req
- xdebug.remote_autostart=1
- xdebug.idekey=PHPSTORM
- 注意：Xdebug 2 与 3 的参数名与默认端口不同，混用会导致无法连接。