很多人把“远程开发”理解成远程桌面，实际上 PHPStorm 在 Ubuntu 上的常见做法更直接：代码可以在本地编辑，但 PHP 解释、运行环境和调试过程都放在远程服务器上。这样既能贴近线上环境，又不用把整个开发体验搬到服务器里。本文按“服务器准备、PHPStorm 连接、远程调试、常见注意点”四步整理，方便你判断每一项配置为什么要做、配完后应该如何验证。
先把 Ubuntu 远程环境准备好
安装并启动 SSH 服务
PHPStorm 连接远程 Ubuntu，底层依赖的就是 SSH。先在服务器上安装并启动 openssh-server：
sudo apt update
sudo apt install openssh-server
sudo systemctl restart sshd随后检查 /etc/ssh/sshd_config，确认允许当前的认证方式：
- 如果使用密码登录，确保存在
PasswordAuthentication yes。 - 如果使用密钥登录，需要提前把公钥放到服务器，通常比密码方式更安全。
安装 PHP 与常用扩展
远程解释器最终会调用服务器上的 PHP，所以先把基础环境装好。文中给出的安装命令如下：
sudo apt update
sudo apt install php php-cli php-mbstring php-xml php-curl php-mysql
# 根据项目需求添加扩展安装完成后，用下面的命令确认版本和可执行状态：
php -v如果你的项目依赖特定版本或额外扩展，这一步就要按实际需求补齐，否则 PHPStorm 能连上远程解释器，也可能在运行时缺模块。
创建项目目录并设置权限
远程开发通常还需要把本地文件同步到服务器，因此项目目录最好提前创建好，并交给实际开发用户管理：
mkdir -p /var/www/html/my_project
sudo chown -R your_username:your_username /var/www/html/my_project
sudo chmod -R 755 /var/www/html/my_project这里的 your_username 需要替换成实际用户名。权限上优先使用 755 或按需要调整到 775，不要为了省事直接改成 777。
临时启动 PHP 内置 Web 服务器
如果只是先验证远程项目能不能跑起来，可以临时使用 PHP 内置服务器：
cd /var/www/html/my_project
php -S localhost:8000这里的 8000 只是示例端口，可以自行调整。需要注意的是，php -S localhost:8000 默认只允许本机访问，后续一般还要配合 PHPStorm 的端口转发、反向隧道，或者直接改用 Apache/Nginx。
在 PHPStorm 里连接远程 Ubuntu
添加远程 PHP 解释器
这一步决定了 PHPStorm 执行脚本、识别运行环境时到底调用哪一套 PHP。配置路径如下：
- 打开
File > Settings > Languages & Frameworks > PHP。 - 点击
CLI Interpreter右侧的...，选择Add。 - 选择
Remote类型，再通过 SSH 填写服务器信息。
SSH 连接时需要填入这些关键参数：
Host：远程服务器 IP 或域名，例如192.168.1.100。Port：SSH 端口，默认22。Username：远程服务器用户名，例如ubuntu。Authentication：可选Password或Key pair，后者更推荐。
连接建立后，再选择远程 PHP 可执行文件路径，通常是 /usr/bin/php。建议点击 Test Connection 做一次验证，确认 PHPStorm 不只是能 SSH 登录，还能正确找到解释器。
配置 Deployment 做文件同步
远程解释器解决的是“用哪台机器执行 PHP”，Deployment 解决的是“本地代码怎么同步到服务器”。在 PHPStorm 中进入：
File > Settings > Build, Execution, Deployment > Deployment- 点击
+新建配置 - 类型选择
SFTP
连接信息里需要重点确认：
SFTP host：远程服务器 IP 或域名。Port：SSH 端口，默认22。Root path：远程项目根目录，例如/var/www/html/my_project。Username/Password：登录账号密码，或改用 SSH 密钥。
随后切换到 Mappings 标签，设置本地目录和远程目录的映射关系：
Local path：本地项目所在路径。Deployment path on server：相对于Root path的目录，填/表示直接映射到根目录。
保存之后，可以通过 Tools > Deployment > Automatic Upload 开启自动上传。这样本地改动保存后，远程项目目录也会随之更新。
配置本地访问入口
如果你希望在本地浏览器里直接访问远程项目，可以继续在 PHPStorm 中配置 Web Server：
- 进入
Run > Edit Configurations。 - 点击
+，添加PHP Built-in Web Server。
常用字段包括：
Name：配置名称，例如Remote Server。Document root：远程项目目录，例如/var/www/html/my_project。Port：本地访问端口，例如8080。Interpreter：前面已经添加好的远程 PHP 解释器。
保存后，就可以通过 http://localhost:8080 在本地浏览器访问远程项目。这里的关键点在于：浏览器打开的是本地地址，但实际运行逻辑仍然走远程环境。
需要断点调试时，再补上 Xdebug
先在远程服务器安装 Xdebug
如果你只需要远程运行代码，到上一步已经够用；如果还要断点、单步调试，就要在远程 Ubuntu 上安装 Xdebug：
sudo apt install php-xdebug修改 php.ini 配置调试参数
找到远程服务器的 php.ini，例如 /etc/php/8.1/cli/php.ini，加入以下配置：
zend_extension=/usr/lib/php/20210902/xdebug.so # Xdebug扩展路径（通过`php -i | grep xdebug.so`获取）
xdebug.mode=debug
xdebug.client_host=127.0.0.1 # 本地IP（若服务器与本地不在同一网络，需改为公网IP或SSH反向隧道）
xdebug.client_port=9003 # 调试端口（默认9003，与PHPStorm一致）
xdebug.start_with_request=yes # 自动启动调试这里最容易出问题的是两个值：
zend_extension：必须对应实际的xdebug.so路径，可以通过php -i | grep xdebug.so查询。xdebug.client_host：如果服务器和本地不在同一网络，127.0.0.1通常不适用，需要改成可达的地址，或通过 SSH 隧道转发。
在 PHPStorm 中完成调试配置
服务器端准备好后，再回到 PHPStorm：
- 进入
Run > Edit Configurations，点击+添加PHP Remote Debug。 - 选择之前配置好的远程解释器。
- 设置
IDE key，默认可用PHPSTORM。 - 点击
Validate，确认Debugger显示为Connected。
接着在代码里打断点，并在 PHPStorm 中执行 Run > Start Listening for PHP Debug Connections。触发调试时，可以直接访问：
http://localhost:8080?XDEBUG_SESSION_START=PHPSTORM如果断点没有命中，优先检查端口 9003、xdebug.client_host 和 IDE 是否处于监听状态。
几个容易踩坑的细节
权限与防火墙别忽略
- 目录权限要保证 PHPStorm 上传文件后可读可写，常见建议是
755或775。 - 防火墙需要放行 SSH 端口
22，以及调试端口9003，否则连接可能建立不了，或 Xdebug 无法回连。
优先考虑 SSH 密钥认证
密码登录虽然配置简单，但长期使用更推荐 SSH 密钥。可以通过 ssh-keygen 生成密钥，再把公钥上传到服务器的 ~/.ssh/authorized_keys。
生产环境尽量不要长期使用内置服务器
php -S 更适合临时验证和本地联调。需要稳定访问时，建议改用 Apache 或 Nginx，并进一步配置虚拟主机、域名解析和正式的运行方式。
