ubuntu下phpstorm如何远程调试

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 的参数名与默认端口不同，混用会导致无法连接。

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