phpstorm在Ubuntu中如何进行远程调试

先说说背景。你本地用PhpStorm开发得好好的，代码一上了Ubuntu服务器就出幺蛾子，是不是挺头疼？其实，搞一个远程调试环境，就像是给服务器装了个“现场直播”的监控器，能让你清清楚楚看到代码在服务器上到底是怎么跑的，哪里出了岔子。下面就把这套流程掰开揉碎了说说。

准备工作，千万别省

动手之前，得先把家伙事儿备齐了。服务器那边，Ubuntu系统得装上PHP（推荐PHP 8.1及以上版本）和Web服务器（Apache或Nginx都行），还得有SSH访问权限。你本地机器上，得装上PhpStorm，版本至少2025.x，别用太老的。

服务器端：安装Xdebug，说难也不难

第一步，是在服务器上把Xdebug装好。直接在终端里敲两行命令就行，事情很简单：

sudo apt-get update
sudo apt-get install php-xdebug

装完它自己就集成进PHP了，但别急着高兴，后面还得调一下配置。

配置Xdebug，关键一步

接下来，得找到PHP的配置文件 php.ini。这玩意儿放哪儿取决于你的PHP运行模式：Apache的通常藏在 /etc/php/8.1/apache2/php.ini，你要是用Nginx+PHP-FPM，那就在 /etc/php/8.1/fpm/php.ini。找到以后，把下面这段加到文件末尾：

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=192.168.1.100  ; 注意！这里改成你本地电脑的IP地址
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.idekey=PHPSTORM
xdebug.log=/tmp/xdebug.log  ; 出问题的时候打开这个日志排查，平时可以关掉

这里有几个地方容易出问题。一是IP地址，一定要写你本地电脑的IP（可以在本地CMD里敲 ipconfig 或者 ifconfig 查）。二是端口 9003，这个要和后面PhpStorm里设的一致。配置完，记得重启Web服务器让改动生效：

# Apache
sudo systemctl restart apache2

# Nginx + PHP-FPM
sudo systemctl restart php8.1-fpm && sudo systemctl restart nginx

PhpStorm端：搭桥牵线，把两头连起来

服务端忙活完了，该轮到本地的PhpStorm了。

1. 配置远程解释器

打开 File > Settings > Languages & Frameworks > PHP，点那个小齿轮，选 Add，然后选 Remote。这里要填关键信息：

• Interpreter：远程服务器上PHP的路径，怎么查？在服务器上敲 which php，出来的结果填进去。
• Sync folders：把本地项目文件夹（比如 /home/user/project）和服务器上的项目文件夹（比如 /var/www/html/my_project）做个映射。
• 最后点 Test Connection，能通就成功了。

2. 设置PHP Servers

接着，进入 PHP > Servers，点 + 新建一个。这里主要是告诉PhpStorm，你的远程服务器长什么样：

• Name：随便起个名，比如 Remote Server。
• Host：填服务器的IP或者域名。
• Port：Web服务的端口，HTTP是80，HTTPS是443。
• Debugger：选 Xdebug。
• 关键一步：勾上 Use path mappings，把本地和服务器上的项目路径再次确认映射一遍。

3. 核对调试端口

进入 PHP > Debug，确保 Debug port 设置成 9003，和服务器上Xdebug的配置一致。再到 DBGp Proxy 标签页，把 IDE key 设成 PHPSTORM，Host 填服务器的IP，端口用默认的 9001 就行。

开搞：启动调试会话

所有配置都到位了，咱们来真格的了：

• 在PhpStorm里打开你要调试的PHP文件，在行号旁边点一下，放个断点（一个小红点）。
• 点顶部工具栏那个电话听筒图标，或者按 Shift+F9，启动调试监听。
• 接下来，打开浏览器访问你的远程项目。有两种办法让程序在断点处停住：
  • 方法一：直接在URL后面加参数，例如 http://你的服务器IP/my_script.php?XDEBUG_SESSION_START=PHPSTORM。
  • 方法二：装个Xdebug Helper浏览器扩展，点击图标，选 Debug 模式，然后正常访问页面就行。

代码跑起来，一旦碰到你设的断点，PhpStorm就会立刻弹出来，并显示Debug工具窗口。你可以在这里看到所有变量的值、函数调用堆栈，然后按 F8（单步跳过）、F7（单步进入）一步步看代码到底是怎么执行的了。

翻车了？别急，常见问题排查

• 端口冲突：万一 9003 端口被谁占用了，可以在服务器和PhpStorm里统一改成其他端口，比如 9007。
• 路径映射错误：这是最常出的问题。确保本地和远程的路径完全对应，可以用PhpStorm里Servers配置中的 Validate remote environment 功能检查一下。
• Xdebug没加载：在服务器上敲 php -m | grep xdebug，看看输出有没有xdebug。如果没有，八成是 php.ini 文件没找对，或者 zend_extension 路径配错了。
• 防火墙拦路：别让服务器防火墙把Xdebug的通信端口（比如9003）给禁了。运行一下 sudo ufw allow 9003/tcp 放行就行。