在 Ubuntu 上使用 PhpStorm 进行远程开发
一 方案总览与选择
- 远程解释器 + 部署（SFTP）：本地编辑，借助 SSH/SFTP 将代码同步到远程服务器，运行与调试使用远程 PHP 解释器。适合已有服务器、希望保留现有运行环境的团队。
- 远程开发 Gateway（JetBrains Client）：在远程服务器启动 IDE 后端，本地用 JetBrains Client 连接，代码与运行环境全在远端，适合资源不足或强调安全合规的场景。
- WSL2 场景：若你的“本地”是 Windows 10/11 + WSL2（Ubuntu），可直接在 WSL 中安装 PHP 并用 PhpStorm 本地连接，无需跨机部署。
以上三种方式均可在 Ubuntu 上落地，按团队与资源选择其一或混合使用。
二 方案一 远程解释器与 SFTP 部署（最常用）
- 前置准备
- 远程服务器安装 OpenSSH 服务 并确保可登录（建议用 SSH 密钥，更安全）：
sudo apt update && sudo apt install -y openssh-server
sudo systemctl enable --now ssh
- 远程安装 PHP（按项目选择版本与扩展）：
sudo apt install -y php php-cli php-mbstring php-xml php-curl php-mysql
- PhpStorm 配置远程解释器
- 打开 File > Settings > Languages & Frameworks > PHP > CLI Interpreter > Add > Remote。
- 选择 SSH，填写 Host/Port/Username，认证方式选 Key pair（推荐）或 Password。
- 指定远程 PHP 路径（可用 which php 查看，如 /usr/bin/php），点击 Test Connection 验证。
- 配置 Deployment（SFTP 同步）
- 打开 File > Settings > Build, Execution, Deployment > Deployment > + > SFTP。
- 填写 SFTP Host/Port/Root path（如 /var/www/html/my_project），在 Mappings 中设置本地与远程目录映射。
- 可开启 Tools > Deployment > Automatic Upload 自动同步。
- 运行与访问
- 新建运行配置：Run > Edit Configurations > + > PHP Built-in Web Server。
- 指定 Document root（远程项目目录）与本地访问 Port（如 8080），Interpreter 选择前面创建的远程解释器。
- 浏览器访问 http://localhost:8080 即可查看远程项目。
该方案稳定、门槛低，适合大多数团队与项目形态。
三 方案二 远程开发 Gateway（JetBrains Client）
- 安装插件：在 PhpStorm 欢迎界面或 File > Settings > Plugins 启用 Remote Development Gateway。
- 建立连接：欢迎界面选择 Remote Development > SSH，填写 IP/端口/用户名/认证方式 并连接。
- 启动后端：选择 IDE 版本来源（自动下载或本地上传），指定远程解压路径，Gateway 将自动部署并启动后端。
- 打开项目：连接成功后，本地会启动 JetBrains Client，像本地 IDE 一样操作远端项目与运行调试。
此方式将计算与代码留在远端，本地仅负责交互，适合对资源与合规要求较高的团队。
四 远程调试 Xdebug 3 配置（可选）
- 远程安装并启用 Xdebug：
sudo apt install -y php-xdebug
- 编辑远程 php.ini（CLI 或 FPM 均可，建议一致），添加：
zend_extension=/usr/lib/php/<版本号>/xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes
说明：若服务器与调试客户端不在同一网络，需将 client_host 设为可到达的地址，或通过 SSH 反向隧道 将本地 9003 转发到服务器。
- PhpStorm 调试
- 打开 Run > Edit Configurations > + > PHP Remote Debug，设置 IDE key（如 PHPSTORM）。
- 启动 Start Listening for PHP Debug Connections，访问
http://localhost:8080?XDEBUG_SESSION_START=PHPSTORM
命中断点后可在调试窗口查看变量与调用栈。
- 常见问题排查
- 断点未命中：检查 Settings > PHP > Servers 的路径映射是否正确。
- 连接失败：确认防火墙放行 9003，并用 telnet 远程IP 9003 测试连通性；必要时开启 xdebug.log 定位问题。
以上配置基于 Xdebug 3，端口默认 9003，与 PhpStorm 保持一致即可。
五 常见问题与优化
- 权限与目录：远程项目目录建议使用 755/775，避免 777；确保部署用户对目录有读写权限。
- 防火墙与端口：开放 SSH 22 与调试端口 9003；如使用云服务器，还需在控制台安全组放行。
- 密钥登录：优先使用 SSH 密钥，在 ~/.ssh/authorized_keys 管理公钥，提升安全性与便利性。
- 性能优化：在 Deployment > Options 中排除 node_modules、日志与缓存目录，减少同步与索引开销。
这些实践能显著降低连接与运行问题的概率，并提升日常开发效率。
