VS Code + Remote-SSH + Ubuntu 虚拟机开发环境搭建指南

1. 目标开发环境

本指南用于在 Windows 主机上使用 VS Code,通过 SSH 连接 VMware Workstation 中的 Ubuntu 虚拟机,并在 Ubuntu 环境中完成 Java 项目的开发。

完成后,开发环境结构如下:

Windows 主机
│
├── VS Code
├── 浏览器
└── SSH 客户端
      │
      │ Remote-SSH
      ↓
Ubuntu 虚拟机
├── JDK
├── Maven
├── Git
├── Node.js(如项目需要)
├── Docker(如项目需要)
└── 项目源代码

项目运行环境统一安装在 Ubuntu 虚拟机中,Windows 主要负责运行 VS Code、浏览器等客户端工具。


2. 前置条件

开始前,请确认:

  1. Windows 已安装 VMware Workstation。
  2. 已创建并可以正常启动 Ubuntu 桌面版虚拟机。
  3. Ubuntu 虚拟机网络正常。
  4. Windows 已安装 VS Code。
  5. Ubuntu 和 Windows 之间能够通过 VMware NAT 网络互通。

推荐 VMware 网络模式:

NAT

例如:

Windows VMnet8:192.168.70.1
Ubuntu:       192.168.70.128
VMware NAT:   192.168.70.2

注意:不同电脑上的 VMware NAT 网段可能不同,应以自己电脑实际地址为准。


3. 在 Ubuntu 中安装 SSH Server

Ubuntu 桌面版通常默认没有安装 SSH Server,因此需要手动安装。

打开 Ubuntu 终端:

sudo apt update
sudo apt install openssh-server

安装完成后检查 SSH 服务:

systemctl status ssh

正常应看到:

Active: active (running)

如果没有启动,可执行:

sudo systemctl enable --now ssh

确认 SSH 正在监听 22 端口:

ss -lntp | grep :22

正常情况下可以看到类似:

LISTEN 0 128 0.0.0.0:22
LISTEN 0 128 [::]:22

4. 查看 Ubuntu 的 当前用户和IP 地址

4.1 查看当前用户

执行:

whoami

例如:

cz

4.2 查看IP地址

执行:

hostname -I

例如:

192.168.70.128

也可以使用:

ip addr

找到 Ubuntu 网卡对应的 IPv4 地址。

4.3 正常地址

例如:

192.168.70.128

说明 Ubuntu 已经通过 VMware DHCP 获得地址。


5. 在 Windows 中测试 SSH

打开 Windows PowerShell。

假设:

Ubuntu 用户名:cz
Ubuntu IP:192.168.70.128

执行:

ssh cz@192.168.70.128

第一次连接时可能出现:

The authenticity of host ... can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入:

yes

然后输入 Ubuntu 用户密码。

如果登录成功,将看到类似:

cz@ubuntu:~$

这说明:

Windows → Ubuntu SSH

已经正常。

必须优先保证命令行 SSH 可以成功,再配置 VS Code Remote-SSH。


6. 安装 VS Code Remote-SSH 插件

打开 VS Code。

进入:

Extensions

搜索:

Remote - SSH

安装 Microsoft 官方插件。

扩展 ID:

ms-vscode-remote.remote-ssh

7. 如果 VS Code 搜索不到 Remote-SSH

有时 Windows 浏览器可以正常联网,但 VS Code 无法访问扩展市场。

这通常不是 Ubuntu 或 SSH 的问题,而是:

  • VS Code 无法访问 Visual Studio Marketplace
  • Windows 系统代理配置异常
  • VPN / TUN / Clash / CordC 等代理软件影响 HTTPS
  • TLS 握手失败

7.1 测试 Marketplace 端口

PowerShell 执行:

Test-NetConnection marketplace.visualstudio.com -Port 443

正常应该出现:

TcpTestSucceeded : True

但是:

TCP 443 可以建立连接,并不代表 HTTPS 一定正常。

还需要继续测试。


7.2 测试 HTTPS

执行:

curl.exe -I https://marketplace.visualstudio.com

正常可能返回:

HTTP/1.1 200 OK

或者:

HTTP/1.1 301
HTTP/1.1 302

这些都属于正常响应。

如果出现:

schannel: failed to receive handshake
SSL/TLS connection failed

说明 HTTPS/TLS 出现问题。


7.3 检查 TUN / 代理软件

如果执行:

Test-NetConnection marketplace.visualstudio.com -Port 443

出现类似:

RemoteAddress    : 198.18.x.x
InterfaceAlias   : CordC
SourceAddress    : 198.18.x.x

通常说明网络流量被代理软件的 TUN/Fake-IP 模式接管。

可以尝试:

  1. 关闭代理软件的 TUN Mode。
  2. 或暂时完全退出 CordC / Clash / Mihomo 等代理程序。
  3. 重新打开 PowerShell。
  4. 再次执行:
curl.exe -I https://marketplace.visualstudio.com

如果 HTTPS 恢复正常,再重新启动 VS Code。


8. 在 VS Code 中添加 Ubuntu SSH 主机

按:

Ctrl + Shift + P

执行:

Remote-SSH: Add New SSH Host

输入:

ssh cz@192.168.70.128

然后保存到默认 SSH 配置文件:

C:\Users\你的Windows用户名\.ssh\config

9. 配置 SSH 别名

打开:

C:\Users\你的Windows用户名\.ssh\config

可以写成:

Host ubuntu-dev
    HostName 192.168.70.128
    User cz
    Port 22

以后可以直接:

ssh ubuntu-dev

VS Code 中也可以直接选择:

ubuntu-dev

10. VS Code 连接 Ubuntu

按:

Ctrl + Shift + P

执行:

Remote-SSH: Connect to Host

选择:

ubuntu-dev

第一次连接可能询问远程系统类型,选择:

Linux

输入 Ubuntu 用户密码。

连接成功后,VS Code 左下角会显示类似:

SSH: ubuntu-dev

此时打开:

Terminal → New Terminal

得到的终端应该是 Ubuntu:

cz@ubuntu:~$

而不是:

PS C:\...

11. 打开 Ubuntu 中的项目

连接 Ubuntu 后:

File
→ Open Folder

选择项目目录,例如:

/home/cz/project

如果是 Maven 项目,建议直接打开包含:

pom.xml

的项目根目录。

例如:

my-project/
├── pom.xml
└── src/
    └── main/
        └── java/

不要只使用:

File → Open File

单独打开某个 Java 文件。

否则 VS Code 可能无法正确识别项目结构。


12. Java 文件无法跳转到声明/定义

常见现象:

  • Ctrl + 鼠标左键无法跳转
  • F12 无效
  • Go to Definition 显示 No definition found
  • Java 类、方法、接口无法导航
  • 自动补全不完整

这种问题通常不是 SSH 引起的,而是:

Ubuntu 远程环境中的 Java Language Server 没有正常工作。


13. 安装 Java 扩展

在 VS Code 已连接 Ubuntu 的状态下打开:

Extensions

搜索并安装:

Extension Pack for Java

至少需要:

Language Support for Java(TM) by Red Hat

必须点击:

Install in SSH: ubuntu-dev

使插件安装到远程 Ubuntu 环境。

安装完成后最好重新加载 VS Code。


14. 学生最终环境检查清单

完成配置后,应能够通过以下项目。

Ubuntu 网络

hostname -I

能够获得:

192.168.x.x

而不是:

169.254.x.x

SSH 服务

systemctl status ssh

状态:

active (running)

Windows SSH

ssh cz@Ubuntu_IP

能够登录 Ubuntu。


VS Code Remote-SSH

VS Code 左下角显示:

SSH: ubuntu-dev

Java 环境

java -version
javac -version
mvn -version

均正常输出版本信息。


Java 扩展

确认:

Language Support for Java(TM) by Red Hat

已经安装在:

SSH: ubuntu-dev

项目功能

能够:

打开完整 Maven/Gradle 项目
Java 代码自动补全
Ctrl + 鼠标点击类名进行跳转
F12 跳转到定义
正常执行 mvn clean compile

15. 常用命令汇总

Ubuntu:

hostname -I
 
systemctl status ssh
 
java -version
javac -version
mvn -version
 
sudo apt update
sudo apt install openssh-server
sudo apt install openjdk-21-jdk
sudo apt install maven

Windows PowerShell:

ping Ubuntu_IP
 
ssh cz@Ubuntu_IP
 
Test-NetConnection marketplace.visualstudio.com -Port 443
 
curl.exe -I https://marketplace.visualstudio.com
 
code --install-extension ms-vscode-remote.remote-ssh

VS Code 常用命令:

Remote-SSH: Add New SSH Host
 
Remote-SSH: Connect to Host
 
Java: Clean Java Language Server Workspace
 
Java: Open Java Projects
 
Java: Import Java Projects into Workspace