Debian上phpstorm远程调试怎么设置

Debian上PhpStorm远程调试设置步骤

搞远程调试这件事，说白了就是让本地的IDE能跟服务器上的PHP代码“对话”，实时看到运行状况。下面从安装到触发，一步步拆解。

1. 安装Xdebug扩展

在Debian服务器上，直接通过包管理器来装，以PHP 8.1为例（记得要跟服务器上PHP版本对上号）：

sudo apt update
sudo apt install php-xdebug

装完后，Xdebug一般会自动加载进来。但最好还是用php --ini确认一下php.ini文件具体在哪，常见的有/etc/php/8.1/cli/php.ini和/etc/php/8.1/fpm/php.ini这两个。

2. 配置Xdebug参数

找到php.ini后，在文件末尾加上这些配置。Xdebug 3的配置跟老版本不太一样，需要注意：

[xdebug]
; 启用Xdebug扩展（路径得跟实际安装位置一致，可以用`php -m | grep xdebug`确认）
zend_extension=xdebug.so
; 设置调试模式为“debug”（Xdebug 3+默认模式就是这个）
xdebug.mode=debug
; 指定PhpStorm所在机器的IP地址（得换成你自己本地的内网或公网IP）
xdebug.client_host=192.168.1.100  # 示例：本地机器的IP
; 指定调试端口（默认是9003，必须跟PhpStorm里配的一致）
xdebug.client_port=9003
; 自动启动调试会话，不用手动传参数
xdebug.start_with_request=yes
; 设置IDE标识（必须跟PhpStorm里的“idekey”一样）
xdebug.idekey=PHPSTORM

保存完后，重启PHP服务让配置生效：

# 如果用的是PHP-FPM
sudo systemctl restart php8.1-fpm

# 如果用的是Apache
sudo systemctl restart apache2

3. 配置PhpStorm远程解释器

这一步是为了让PhpStorm能认得出远程服务器的PHP环境。操作路径如下：

1. 打开PhpStorm，进File > Settings > PHP。
2. 点CLI Interpreter旁边的齿轮图标，选Add。
3. 选择SSH Interpreter，填上远程服务器的IP、端口（默认22）、用户名（比如root）。
4. 选好认证方式（密码或密钥），点Next。
5. 在Interpreter那栏写上远程PHP的路径（通常是/usr/bin/php），PhpStorm会自动检测PHP版本和扩展信息。
6. 点Finish保存。

4. 配置远程服务器连接（Deployment）

为了让PhpStorm能同步本地和远程的文件，得配一个SFTP连接：

1. 进File > Settings > Deployment > Configuration，点+添加新服务器。
2. 输入服务器名称（比如Debian-Remote），类型选SFTP。
3. 填上远程服务器的Host（IP地址）、Port（22）、Username、Password/Key。
4. 在Root path填上远程项目的根目录（比如/var/www/html/myproject）。
5. 点Test Connection测试一下，成功后勾选Automatic upload（这样本地文件保存后会自动上传到服务器）。
6. 切到Mappings标签，设置路径映射：
   • Deployment path on server：远程项目在服务器上的路径（如/var/www/html/myproject）。
   • Local path：本地项目的路径（如/Users/username/projects/myproject）。
   • Web server root URL（可选）：远程项目的访问URL（如http://myproject.example.com），方便预览。

5. 配置PhpStorm调试监听

1. 进Run > Edit Configurations，点+添加一个PHP Remote Debug配置。
2. 在Server下拉菜单里选之前配好的远程服务器（如Debian-Remote）。
3. 确认Debugger是Xdebug，IDE key是PHPSTORM（跟php.ini里的一致）。
4. 点OK保存。
5. 点PhpStorm右上角的电话图标（Start Listening for PHP Debug Connections），开始监听调试（图标会变绿）。

6. 触发调试会话

触发调试有两种常见方式：

• 方式一：浏览器加参数
  访问远程项目时，在URL后面加上XDEBUG_SESSION_START=PHPSTORM参数（比如http://myproject.example.com?page?XDEBUG_SESSION_START=PHPSTORM），或者装个Xdebug Helper浏览器插件一键开启。
• 方式二：代码里触发
  在需要调试的代码行左侧点一下设置断点，然后通过PhpStorm的Run > Debug选择对应的PHP Remote Debug配置启动。

注意事项

• 防火墙设置：确保远程服务器的防火墙开放了xdebug.client_port（如9003）的入站连接，可以用sudo ufw allow 9003。
• 路径映射：Mappings配置是调试的核心，如果路径对不上，PhpStorm就没法正确定位断点。这是最容易翻车的地方。
• Xdebug版本：Xdebug 3+的配置参数跟2.x差别很大（比如xdebug.remote_enable已经变成xdebug.mode=debug），别拿老套路来套新版本。

走完这七步，当代码执行到断点时，PhpStorm就会自动停下并显示调试信息。接下来就能单步执行、看变量、分析调用栈了，基本跟本地调试没区别。