VSCode远程连接阿里云ECS服务器

环境

• 服务器：阿里云ECS服务器（CentOS 8.5 64位）
• 客户端：Windows 11 专业版
• VSCode 1.103.0 （在Windows客户端）

背景

现有阿里云ECS服务器（CentOS 8.5 64位），服务器上部署了Apache和ThinkPHP。现在的需求是要持续开发和调试代码，如果能够直接在服务器上开发和调试，那就方便多了。但是，服务器本身只有2核CPU和2GB内存，如果安装图形界面，再安装VSCode等工具，恐怕服务器的性能无法支撑。

一个解决办法是：在本地（Windows 11）安装VSCode，然后把VSCode连接到远程服务器，实现可以编辑、调试远程服务器代码的功能。整个过程中，远程服务器不需要安装图形界面，也不需要安装VSCode。

步骤

准备工作

首先要在ECS服务器上安装好Apache、PHP、Composer、ThinkPHP等，并配置好，确保其工作正常。详细步骤可参见我另一篇文档 https://blog.csdn.net/duke_ding2/article/details/150657401 。

配置VSCode

服务器搞定之后，现在开始配置客户端。

在客户端（Windows 11），首先要配置好SSH的 config 文件，其路径为： C:\Users\Administrator\.ssh\config ，内容如下：

Host ding1HostName <公网IP>User dingIdentityFile "C:\Users\Administrator\.ssh\ding.pem" 

注意要把 <公网IP> 替换成ECS服务器的公网IP地址。

验证一下，确保可通过 ssh ding1 免密登录到服务器上。

接下来，安装VSCode，过程略。

打开VSCode，按下 Ctrl + Shift + P ，打开命令面板，选择 Remote-SSH: Open SSH Configuration File... ：

然后选择前面提到的 config 文件：

这样，就会在VSCode里打开 config 文件，可以在此编辑该文件。

现在，再次按下 Ctrl + Shift + P ，打开命令面板，选择 Remote-SSH: Connect to Host... ：

选择 config 文件里配置的Host信息：

这时，就会弹出一个新的VSCode窗口，窗口右下角会显示服务器的setup进度：

如果一切顺利的话，过一会儿setup就会成功，如下：

注意：左下角显示 SSH: ding1 ，表示已经连接到远程服务器了。

注：download和setup做了啥呢？检查一下服务器端，会发现 ding 账号的根目录下多出了 .vscode-server 目录：

[ding@iZ2ze46sxirvp17kje7v84Z .vscode-server]$ tree -L 4
.
├── cli
│   └── servers
│       ├── lru.json
│       └── Stable-e3550cfac4b63ca4eafca7b601f0d2885817fd1f
│           ├── log.txt
│           ├── pid.txt
│           └── server
├── code-e3550cfac4b63ca4eafca7b601f0d2885817fd1f
├── data
│   ├── CachedProfilesData
│   │   └── __default__profile__
│   │       ├── extensions.builtin.cache
│   │       └── extensions.user.cache
│   ├── logs
│   │   └── 20250824T142857
│   │       ├── exthost1
│   │       ├── exthost2
│   │       ├── exthost3
│   │       ├── ptyhost.log
│   │       ├── remoteagent.log
│   │       └── remoteTelemetry.log
│   ├── Machine
│   ├── machineid
│   └── User
│       ├── globalStorage
│       ├── History
│       │   └── 2206329d
│       └── workspaceStorage
│           └── ab4efd142e702c229ee52cfa1c37a2f3
└── extensions└── extensions.json20 directories, 11 files

里面都是一些与VSCode server相关的东西。

常见问题

如果VSCode连接失败，会弹出一个报错对话框，但是报错信息可能不是非常明确。此时可以关闭对话框，然后点开“OUTPUT”页签，查看log里详细的报错信息。

不符合先决条件

如下图所示：

查看log可知，是因为CentOS 7.9的 libstdc++ 不符合条件：

The remote host may not meet VS Code Server's prerequisites for glibc and libstdc++ (The remote host does not meet the prerequisites for running VS Code Server)

貌似是因为VSCode是较新的版本，而服务器是CentOS 7.9，版本太老了，无法满足VSCode的需求。后来我把ECS服务器换成了CentOS 8.5，就没这个问题了。

下载VSCode Server失败

如下图所示：

这有可能是网络问题，可以多试几次，或者加上网络代理试试。

编辑源码

前面的工作完成后，VSCode已经连接到远程服务器了。此时点击“Open Folder…”，并输入要打开的目录，注意这个目录是远程服务器上的目录，比如 /var/www/html/aaa （这是ThinkPHP项目 aaa 的根目录）：

点开左边的“扩展”页签，在远程安装PHP插件（本地可能也需要安装PHP插件）：

现在，我们试着编辑一下远程服务器上的文件。比如，打开 app/controller/Index.php 文件（这是ThinkPHP默认的Controller）：

如上图所示，给 Index 类添加一个方法 test() ：

    public function test() {return 'OK';}

接下来，在浏览器里访问 http://<公网IP>/index/test ：

可见，修改生效了。

这样，有了VSCode图形化界面IDE，极大的方便了远程服务器上的代码开发工作。

单步调试

如果能够单步调试远程服务器的代码，那就更好了。

首先要在远程服务器上安装Xdebug：

sudo dnf install -y php-xdebug

接下来，编辑服务器上的 /etc/php.d/15-xdebug.ini 文件（可用 php --ini 查看配置文件信息），添加如下内容：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.idekey=VSCODE
xdebug.log=/var/log/xdebug.log
xdebug.log_level=7; 可选配置：自动触发调试（适合初学者）
xdebug.start_upon_error=yes; 可选配置：仅通过特定参数触发调试（更推荐）
; xdebug.start_with_request=trigger
; xdebug.trigger_value=VSCODE

注意：这里的 client_host 设置为localhost，下面会解释原因。

打开9003端口：

sudo iptables -I INPUT -p tcp --dport 9003 -j ACCEPT

重启 php-fpm 服务：

sudo systemctl restart php-fpm

查看Xdebug：

$ php -v
Cannot load Xdebug - it was already loaded
PHP 8.4.11 (cli) (built: Jul 29 2025 15:30:21) (NTS gcc x86_64)
Copyright (c) The PHP Group
Built by Remi's RPM repository <https://rpms.remirepo.net/> #StandWithUkraine
Zend Engine v4.4.11, Copyright (c) Zend Technologieswith Zend OPcache v8.4.11, Copyright (c), by Zend Technologieswith Xdebug v3.4.5, Copyright (c) 2002-2025, by Derick Rethans

注意最后一行的Xdebug信息，说明Xdebug已经配置好了。

现在来梳理一下debug流程：从浏览器访问服务器，代码在服务器上运行，而断点和调试是在本地操作的，所以从浏览器访问服务器时，服务器要把调试请求转发到本地。Xdebug监听9003端口，所以我们可以建立一个SSH tunnel，把服务器上9003端口的请求转发到本地的9003端口。

这里有个问题：由于本地客户端是在内网里面，没有公网IP，其IP地址是 192.168.1.xxx ，所以从服务器是无法直接连接到本地端的。解决办法是建立一个反向ssh tunnel（ssh命令是从本地连接到服务器，而请求转发是从服务器到本地）：

ssh -R 9003:localhost:9003 ding1

这样，发送到服务器上9003端口的请求，就会被转发到本地（注：命令里的localhost指的是本地，即Windows端）的9003端口。

这就解释了刚才在服务器的 /etc/php.d/15-xdebug.ini 文件里，为什么要把 client_host 设置为 localhost （注：这里的localhost指的是服务器的localhost）。这是因为从服务器无法把debug请求直接发送到客户端，所以要先发到本地（服务器），然后通过tunnel转发到客户端。

现在，点开VSCode左边的“Run and Debug”页签，创建 launch.json 文件，一般来说，直接保存即可，其中 Listen for Xdebug 配置如下：

......{"name": "Listen for Xdebug","type": "php","request": "launch","port": 9003,"log": true,"externalConsole": false,"pathMappings": {"/var/www/html/aaa": "${workspaceFolder}"}}
......

然后点开下拉箭头，选择“Listen for Xdebug”：

在源代码里设置好断点，然后选择 Run -> Start Debugging ，如下图所示：

一切准备就绪！

此时，只要在浏览器里访问 http://39.106.21.57/index/test ，断点就会立即生效：

大功告成！

这样，我们就能够从客户端（Windows 11）的VScode，来编辑和调试远程服务器上的代码了。