Linux环境下 PhpStorm 远程开发实操指南
一 前期准备
- 在远程服务器(如 CentOS/Ubuntu/Debian)安装并确认 PHP CLI 可用:
php -v;如使用 PHP-FPM/Apache/Nginx,确保服务可正常运行。
- 建议配置 SSH 免密登录:本地执行
ssh-keygen -t rsa,将公钥复制到服务器 ssh-copy-id user@server_ip,测试 ssh user@server_ip 无需密码即可登录。
- 本地安装 PhpStorm Linux 版 并准备项目。以上准备可显著提升连接与后续同步、调试的稳定性与效率。
二 配置 Deployment 文件同步
- 打开 File > Settings > Build, Execution, Deployment > Deployment,新建配置,类型选 SFTP:
- 填写 SFTP host、Port(默认 22)、Root path(如:/var/www/html/project);
- 认证方式选 Key pair(推荐) 或 Password;
- 点击 Test Connection 验证连通性。
- 在 Mappings 标签设置路径映射:
- Local path:本地项目绝对路径;
- Deployment path on server:相对于 Root path 的服务器路径;
- 可选 Web server root URL(如:
http://your-domain/)。
- 按需启用自动上传:勾选 Tools > Deployment > Automatic Upload,保存后本地变更将自动同步到服务器。
三 配置远程 PHP 解释器
- 打开 File > Settings > Languages & Frameworks > PHP,点击齿轮选择 Add > SSH Interpreter:
- 可直接新建 SSH 连接,或选择上一步的 Deployment 配置 复用连接;
- 指定远程 PHP 可执行文件路径(常见如:/usr/bin/php),PhpStorm 会自动检测已安装扩展;
- 如项目使用 Composer,可在解释器选项中指定 Composer 路径(如:
--with-composer=/usr/local/bin/composer)。
- 验证:在 PhpStorm 的终端运行
php -v、composer -V,应显示远程环境信息。
四 配置 Xdebug 远程调试
- 服务器端安装并启用 Xdebug(以 Xdebug 3.x 为例):
- 安装:
sudo pecl install xdebug(需提前安装 php-devel/gcc/make 等依赖);
- 在 php.ini 或 /etc/php.d/xdebug.ini 添加:
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes(或按需设为 trigger 以按需触发)
xdebug.client_host=YOUR_LOCAL_IP(本机局域网/公网 IP)
xdebug.client_port=9003(与 PhpStorm 一致)
xdebug.idekey=PHPSTORM
- 重启服务:
sudo systemctl restart php-fpm 或 sudo systemctl restart apache2。
- PhpStorm 端:
- 点击右上角 Start Listening for PHP Debug Connections(电话图标);
- 新建 Run/Debug Configuration:类型选 PHP Web Page,选择前面创建的 Server,设置 Start URL(如:
/index.php);
- 确保 Mappings 正确,使服务器文件路径映射回本地项目;
- 触发调试:浏览器访问
http://your-domain/index.php?XDEBUG_SESSION_START=PHPSTORM,或使用 Xdebug Helper 插件一键开启。
五 常见问题与排查
- 连接失败:检查 SSH 端口/防火墙/SELinux,确认 Test Connection 成功;密钥权限应为 600。
- 文件不同步:确认 Mappings 路径正确,必要时手动 Upload to 或开启 Automatic Upload。
- 调试未触发:核对 xdebug.client_host/port/idekey 与 PhpStorm 一致;如使用 CLI 调试,需设置环境变量
export XDEBUG_SESSION=1 后再执行脚本。
- 版本兼容:老项目若仍使用 Xdebug 2.x,常见配置为
xdebug.remote_enable=1、xdebug.remote_host、xdebug.remote_port=9000、xdebug.remote_autostart=1,与 Xdebug 3.x 参数差异较大,建议优先升级并按 3.x 规范配置。