PHPStorm 在 Ubuntu 上的远程开发配置
一 环境准备
- 在本地 Ubuntu 安装并启动 PHPStorm（Linux 版）。
- 在远程 Ubuntu 主机安装 SSH 服务器 与 PHP CLI：
- 安装与启动 SSH：sudo apt update && sudo apt install -y openssh-server && sudo systemctl enable --now sshd
- 安装 PHP：sudo apt install -y php php-cli
- 建议创建专用开发用户（可选）：sudo adduser remoteuser；如需密钥登录，将本地公钥放入远程的 ~/.ssh/authorized_keys。以上完成后，远程主机即可通过 SSH 访问，且具备 PHP 运行环境。
二 配置远程解释器
- 打开 PHPStorm：File → Settings → Languages & Frameworks → PHP → CLI Interpreter → 点击齿轮 → Add。
- 选择 SSH Interpreter，填入远程 Host、Port 22、Username，认证方式可选 Password 或 Key pair（OpenSSH 或 PuTTY）。
- 指定远程 PHP 可执行文件路径（常见为 /usr/bin/php），PHPStorm 会自动检测版本与扩展；保存后将项目解释器切换为远程。这样运行与测试将使用远程环境。
三 配置 SFTP 部署与路径映射
- 打开：Tools → Deployment → Configuration → 新建 SFTP，填写 Host、Port 22、Root path（如 /var/www/html/project）、认证方式。
- 在 Mappings 中设置：
- Local path：本地项目根目录
- Deployment path：远程项目相对路径（如 / 或 /project）
- 选项建议：勾选 Upload changed files automatically to the default server 实现保存即同步；需要时开启 Download on explicit save 或手动 Sync 保持一致性。
四 远程运行与调试
- 运行脚本/命令：Run/Debug Configurations 选择 PHP Script 或 PHP Built-in Web Server，解释器选择上一步的 Remote PHP。内置服务器可指定 Host 0.0.0.0、Port 8000 与 Document root（远程项目目录），通过浏览器访问 http://服务器IP:8000。
- 远程调试（Xdebug 3）：
- 安装扩展：sudo apt install -y php-xdebug
- 在远程 php.ini（CLI 与 FPM/Apache 各一份按需配置）添加：
- zend_extension=xdebug
- xdebug.mode=debug
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003
- xdebug.start_with_request=yes
- xdebug.idekey=PHPSTORM
- 重启服务：sudo systemctl restart apache2 或 php-fpm
- PHPStorm：Settings → PHP → Debug，确认 Debug port=9003；Settings → PHP → Servers 新增服务器（Name 与 Host 一致），设置 Use path mappings 将本地路径映射到远程；工具栏开启 Start Listening for PHP Debug Connections，浏览器访问时在 URL 附加 ?XDEBUG_SESSION_START=PHPSTORM 触发断点。
五 常见问题与排查
- 连接失败：检查远程 sshd 是否运行（sudo systemctl status ssh），云服务器安全组/防火墙是否放行 22 端口；密钥权限应为 600，远程 ~/.ssh/authorized_keys 权限 700/600。
- 解释器不可用：确认远程 /usr/bin/php 存在且可执行（which php），必要时在 CLI 配置中手动指定路径。
- 路径映射错误：CLI 运行正常但浏览器访问 404/500，多为 Document root 或 Mappings 不一致；同步后清理远程缓存并重新访问。
- 调试无法连接：确认 xdebug.mode=debug、client_host=127.0.0.1、client_port=9003 与 PHPStorm 一致；如使用 Docker/Nginx，确保端口与路由转发正确。
