概述
本文是一篇工作笔记和备忘，记录在Windows+VSCode开发环境中，配置Remote SSH远程项目的过程和要点。
笔者在最近的开发工作中，经常遇到需要对远程Linux系统上的代码进行维护的工作。
笔者标准的开发环境是Windows系统，而一般的生产环境则是Linux系统。虽然nodejs和bun应用基本上都是跨平台的，这并不是一个太大的问题。但毕竟还是两个不同的操作系统平台，在个别配置和细节上，还是有所差异，对应用的执行会产生一些影响。所以笔者一般的工作流程是，在Windows系统上，开发和简单测试完成之后，会将代码部署到一个和生产环境相近的Linux系统中，进行进一步的验证和测试，如果没有问题就可以部署到生产环境中了。
这里有一个问题就是，如果在Linux测试环境中，遇到了和平台相关的问题之后，其修正和再测试，是不太方便的，但又由于Linux环境本身的限制，比如无GUI，其他操作如代码编辑和调试，资料查询又不方便等等，又不方便直接在Linux系统上开发。
所以，一个比较理想的情况是，代码的编辑和调试，还是在Windows下进行(如使用VSCode)，但真正运行，却在真正的Linux环境中。这就是VSCode Remote SSH扩展模块提供的功能特性和解决的问题。
Remote SSH是一个VSCode的扩展模块，它可以使用SSH协议，连接远程的主机，并且在远程环境中，执行并调试当前项目的代码。这里要注意的就是这个特性，它并不是简单的访问远程主机上的代码(这个可以通过映射网络文件系统达成)而是可以在远程环境中执行代码，并提供完整的调试体验，就和在本地主机中的代码项目一样。
通过观察和理解这个模块的安装和配置过程，笔者猜想和理解它的基本原理，并不是简单的使用SSH连接远程主机并且映射项目文件夹，而是在远程主机上，安装并运行了一个名为"VSCode Server"的程序，来管理远程代码的执行和调试，并且负责和本地的VSCode进行通信协调，提供本地开发调试一样的应用体验。
为了让读者能够更直观的理解和体验这个特性和原理，笔者通过下面的实际操作过程，来进一步说明。
实操环节
远程主机和项目
首先需要先准备好远程主机，和需要开发和调试的项目。
远程主机就是一个标准的Linux系统，笔者的测试环节，就是Windows11自己带的WSL2-Debian系统，内核是6.6(如下)。
js
uname -a
Linux DESKTOP-OG70260 6.6.87.2-microsoft-standard-WSL2 #1 SMP PREEMPT_DYNAMIC Thu Jun 5 18:30:46 UTC 2025 x86_64 GNU/Linux
## 安装openssh-server
sudo apt install openssh-server
openssh-server is already the newest version (1:10.0p1-7).
Summary:
Upgrading: 0, Installing: 0, Removing: 0, Not Upgrading: 0
## 确认ssh服务
ss -lpnt
State Recv-Q Send-Q Local Address:Port Peer Address:Port Process
LISTEN 0 128 0.0.0.0:22 0.0.0.0:*
LISTEN 0 1000 10.255.255.254:53 0.0.0.0:*
## 安装和配置开发支撑软件
sudo apt install git build-essential
[sudo] password for yanjh:
git is already the newest version (1:2.47.3-0+deb13u1).
build-essential is already the newest version (12.12).默认情况下，windows的WSL2是通过应用程序项目(如Debian)直接进入和操作的，并没有像一般Linux系统一样，通过远程的SSH连接操作，所以也没有安装SSH服务。这里需要先安装配置一下。然后可以使用ss命令，检查一下ssh服务是否正常启动，并且监听了网络端口(22)。
随后，可以考虑预先安装和配置一些常用的软件开发相关的软件，如git、build-essential等等，相当于准备一个相对完善的Linux开发环境。
远程开发项目，可以就是一个简单的项目文件夹(此处为~/Develop/btest)，不需要其他实际内容，甚至也可以不存在，我们可以在后续创建并将其配置成为开发项目。
至此，在服务器端的工作，就基本上完成了。随后的操作，都在开发客户端方面完成(Windows系统和VSCode软件)。
确认SSH连接
在正式开始之前，最好能够确认一下，在开发环境中，可以使用ssh正常的连接开发目标服务器，并且能够确认相关参数的正确性，还能确认服务器的SSH服务工作正常并能够正常连接，保证整个连接机制和环节是正常的。
最简单的方式，就是开发环境所在的主机，向远程目标主机，发起一次完整的ssh连接：
js
## 假设目标服务器地址为 172.20.185.14，连接用户为yanjh
ssh yanjh@172.20.185.14
## 如果是初次连接，确认并记录服务器公钥
The authenticity of host '172.20.185.14 (172.20.185.14)' can't be established.
ED25519 key fingerprint is SHA256:4xGpX5q5uYqSkT3bHyqSmowGQBhYetDvCXUrAqEO5Rg.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
## 输入密码并正常登录
yanjh@172.20.185.14's password:
Linux DESKTOP-OG70260 6.6.87.2-microsoft-standard-WSL2 #1 SMP PREEMPT_DYNAMIC Thu Jun 5 18:30:46 UTC 2025 x86_64如果这个测试能够通过，就表明从客户端到服务器的整个链条，包括ssh客户端、配置信息、网络地址和端口、用户名和密码、ssh服务器、服务器账号信息，都是正确的。
Remote SSH扩展
前面已经提到，要让VSCode可以实现远程开发和调试，核心是Remote SSH扩展模块。这个模块可以在扩展市场中安装。下图为在VSCode扩展市场中，搜索并安装Remote SSH：
默认的第一个搜索结果，应该就是，注意确认这个扩展程序，来自Microsoft。
远程主机配置和连接
Remote SSH扩展模块安装完成之后，就可以开始配置远程主机的连接了。方法是在VSCode中，按F1,会调出VSCode的命令菜单，输入Remote SSH，可以查找相关的项目(下图)。
由于是新的环境，这里需要先增加一个新的主机连接方式。
选择"Add New Host..."(创建主机)，按照提示输入远程主机的IP地址，连接用户名等信息。这其实是一个向导的方式，也可以直接选择"Config SSH Host..."，它会打开并编辑一个配置文件，一般为~/.ssh/config，就可以直接编辑其中的项目，完成配置工作。
增加SSH主机：
配置SSH主机：
配置文件：
配置好主机项目之后，再次按F1呼叫Remote SSH菜单项目，这次选择"Connect To Host..."(连接主机)项目，然后选择预配置的主机，可能需要输入密码，就可以连接到远程主机了：
如果连接成功，在初始的情况下，VSCode Remote SSH模块，会向远程主机下载并安装一个"VSCode Server"服务，这个过程需要稍等片刻，然后它会打开一个新的窗口，注意其左下角的连接信息，表明现在的环境，其实已经是在远程主机当中了。这时选择"Open Folder"，就不再是向往常一样，打开一个本地文件选择对话框，而是在输入栏中，提示选择远程主机中的文件夹路径了：
然后我们选择前面创建的项目文件夹，就可以打开项目文件，和原来的开发体验基本一致：
可以看到，这里的UI，和原来稍有不同，有基本要点：
- 标题上，显示这是一个远程项目
- 左下角可以看到连接信息
- 项目的组织方式，是远程文件夹的组织方式
- Terminal，其实是远程主机的终端
- 在Terminal中，执行的命令，也是在远程执行的，并不是当前开发工具所在的Windows环境当中
- 其他功能包括编辑、调试、测试等等，都和标准Windows开发环境无异
如果觉得中间经常要输入密码比较不便，可以将SSH配置成为公钥登录的模式。
小结
本文探讨了在Windows/VSCode的开发环境当中，如何配置和使用Remote SSH扩展，来连接和调试一个远程Linux系统之上的程序项目，包括了基本原理分析，体验和优势，Remote SSH的安装和配置过程等内容。