三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

VScode远程连接Ubuntu虚拟机：SSH方案配置与网络问题深度解析

发布时间：2026/8/16 13:14:42 三亩地 编程学习日记
VScode远程连接Ubuntu虚拟机：SSH方案配置与网络问题深度解析

1. 项目概述：为什么我们需要VScode远程连接Ubuntu虚拟机？

作为一名常年穿梭于Windows、Linux和各类云服务器之间的开发者，我深知在不同环境间切换编码的痛苦。你可能在Windows上享受着熟悉的操作界面和丰富的办公软件，但项目的编译、部署和运行环境却要求是Linux，特别是Ubuntu。直接在Windows上搞个WSL（Windows Subsystem for Linux）是个选择，但对于需要完整Linux内核特性、特定虚拟机网络拓扑（比如搭建分布式集群）或者资源隔离的场景，在VMware或VirtualBox里跑一个Ubuntu虚拟机依然是更经典、更可控的方案。

问题来了：你愿意在虚拟机那小小的窗口里，用着可能不太顺手的终端编辑器（如vim、nano）写代码吗？或者频繁地在主机和虚拟机之间拖拽文件？效率太低下了。这时，VScode的“远程开发”功能就成了救星。它允许你将本地的VScode变成一个纯粹的“前端界面”，而所有的代码编辑、终端操作、插件运行都实际发生在远程的Ubuntu虚拟机中。你获得的是本地VScode的流畅体验和强大生态，同时享受Ubuntu原生环境的纯粹与兼容性。这不仅仅是连接，更是一种开发范式的转变，将本地IDE的便利性与远程服务器的能力无缝融合。

简单来说，这个方案解决了几个核心痛点：第一，环境一致性，保证开发、测试、生产环境统一；第二，性能隔离，编译等重负载任务在虚拟机内进行，不影响主机；第三，体验提升，在熟悉的VScode里操作一切，无需适应虚拟机内的GUI或纯终端。接下来，我将手把手带你完成从零开始的配置，并分享我趟过的所有坑和最终沉淀下来的稳定方案。

2. 核心原理与方案选型：SSH为何是唯一推荐？

要实现VScode远程连接，底层通信协议是关键。你可能听过一些其他方式，比如利用VScode的“隧道”功能或者一些第三方插件，但经过多年实践，SSH（Secure Shell）是唯一稳定、安全、高效且官方全力支持的标准方案。VScode的“Remote - SSH”扩展就是围绕SSH构建的。

2.1 为什么是SSH？

  1. 安全性：SSH天生为加密远程登录而设计，所有传输数据（包括密码、命令、文件）都经过加密，避免了在局域网甚至公网上明文传输的敏感信息泄露风险。这是任何生产级开发都必须考虑的基础。
  2. 普遍性与稳定性：SSH是Linux/Unix系统的标准服务，Ubuntu默认安装并可以轻松开启。其协议成熟，网络兼容性极好，穿透各种NAT和防火墙的成功率相对较高（尤其是在配置了端口转发的情况下）。
  3. 功能完整性：SSH不仅仅是一个登录通道。它支持端口转发（用于调试）、SFTP（用于文件传输），而VScode Remote正是利用SSH通道建立了一个稳定的、支持多种服务的连接，使得代码智能感知、插件安装、终端访问等都能流畅进行。
  4. 官方支持与生态：微软官方开发的“Remote - SSH”扩展体验最为完善，更新及时，与VScode核心功能集成度最高。它本质上是一个“SSH客户端+远程环境管理器”，而不是一个简单的文件同步工具。

2.2 与其他方式的对比

  • 直接使用虚拟机共享文件夹：在虚拟机软件中设置共享文件夹，然后在主机VScode中打开这个共享目录。这种方式的问题是，文件操作（尤其是大量小文件）的I/O性能损耗大，并且文件权限（Linux的rwx）在Windows共享下管理混乱，容易导致脚本无法执行等问题。
  • 第三方同步插件：需要双向监控和同步文件，配置复杂，且实时性难以保证，容易产生冲突。
  • RDP或VNC连接虚拟机桌面：这相当于远程桌面，会传输整个GUI界面，带宽占用高，延迟明显，且你仍然是在虚拟机的桌面环境里用一个可能不那么好用的编辑器。

因此，SSH方案是性能和体验的最优解。它让你感觉像是在本地开发，但所有计算都在远程。

2.3 整体连接架构图（逻辑描述）

理解连接架构有助于排查问题：

  1. 主机（Windows/Mac）：运行VScode，并安装了“Remote - SSH”扩展。扩展充当SSH客户端。
  2. 网络桥梁：虚拟机网络需要配置为“桥接模式”或“NAT模式+端口转发”，确保主机能通过IP地址访问到虚拟机的22号端口（SSH默认端口）。
  3. 客体机（Ubuntu虚拟机）：运行sshd服务，监听22端口，接受来自主机的SSH连接。连接建立后，VScode扩展会在客体机上自动安装一个轻量级的“VS Code Server”，这个Server负责与主机上的VScode前端通信，执行具体的编辑、插件等命令。

整个过程中，你的代码文件始终只存在于Ubuntu虚拟机中，VScode界面只是它们的“镜像”视图。

3. 环境准备：虚拟机、Ubuntu与SSH服务配置

工欲善其事，必先利其器。稳定的连接始于一个正确配置的基础环境。

3.1 虚拟机与Ubuntu安装要点

如果你已经有一个可用的Ubuntu虚拟机，可以跳过此步，但请务必核对网络配置。

  1. 虚拟机软件选择：VMware Workstation Player（免费）或 VirtualBox（免费）均可。VMware在性能和网络配置上通常更简单稳定一些，本文以VMware为例，但原理通用。
  2. Ubuntu镜像下载：建议从Ubuntu官网下载最新的LTS版本，如22.04 LTS。LTS版本提供长期支持，更稳定。
  3. 虚拟机创建关键设置：
    • 网络适配器：这是重中之重。创建时或创建后，在虚拟机设置中，将网络连接设置为“桥接模式”。桥接模式会让虚拟机从你的家庭路由器获取一个和主机同网段的独立IP地址（如192.168.1.x），就像一台真实的新电脑接入了你的局域网。这是最推荐的方式，连接最简单。
    • 如果无法使用桥接（例如公司网络有限制），则使用“NAT模式”。在NAT模式下，虚拟机处于一个虚拟子网中，主机可以访问它，但外部网络不能直接访问虚拟机。此时，你必须在虚拟机软件中设置“端口转发”，将主机的某个端口（如2222）转发到虚拟机的22端口。具体设置在VMware的“编辑”->“虚拟网络编辑器”中，找到NAT模式的网络，点击“NAT设置”，添加一条转发规则。
    • 内存与CPU：根据你的开发需求分配，建议至少2核CPU，4GB内存。运行VScode Server本身需要一定资源。
  4. 安装Ubuntu：按照向导安装，建议选择“最小化安装”以减少不必要的软件包。务必记住你设置的用户名和密码。

3.2 Ubuntu系统内SSH服务安装与配置

Ubuntu桌面版默认可能没有安装SSH服务器。

  1. 打开终端：在Ubuntu虚拟机内，按Ctrl+Alt+T打开终端。
  2. 安装OpenSSH服务器：
    sudo apt update sudo apt install openssh-server
  3. 检查服务状态：安装后，SSH服务通常会自动启动。可以通过以下命令检查：
    sudo systemctl status ssh
    如果看到active (running)，说明服务正在运行。如果没有运行，使用sudo systemctl start ssh启动它，并使用sudo systemctl enable ssh设置开机自启。
  4. （可选但推荐）配置密钥登录：使用密码登录每次都需要输入，且安全性稍弱。配置SSH密钥对是更优选择。
    • 在主机生成密钥对（如果还没有）： 在Windows上，如果你安装了Git Bash，可以使用它的终端。或者使用Windows 10/11自带的PowerShell或CMD。
      # 在PowerShell或Git Bash中执行 ssh-keygen -t rsa -b 4096
      一路回车，使用默认路径（C:\Users\你的用户名\.ssh\id_rsa）。
    • 将公钥复制到Ubuntu虚拟机： 首先，在Ubuntu终端查看你的用户名：whoami。假设用户名为developer。 然后，在主机上执行以下命令，将公钥内容复制到虚拟机的授权文件中：
      # 替换`192.168.1.100`为你的虚拟机IP，`developer`为你的用户名 ssh-copy-id developer@192.168.1.100
      如果提示命令不存在，可以手动操作：先将主机~/.ssh/id_rsa.pub文件内容复制出来，然后在Ubuntu虚拟机中执行：
      mkdir -p ~/.ssh echo “你复制的公钥内容” >> ~/.ssh/authorized_keys chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys
  5. 获取虚拟机IP地址：在Ubuntu终端中执行ip addr show或ifconfig（需安装net-tools）。在输出中找到你的主要网卡（通常是ens33或eth0），查看inet后面的地址，例如192.168.1.100。记下这个IP。

注意：如果虚拟机使用NAT模式且未设置端口转发，主机是无法通过这个IP直接连接虚拟机的。必须使用端口转发后的主机IP和端口。

4. VScode配置与远程连接实战

基础环境就绪，现在进入核心的VScode配置环节。

4.1 安装Remote-SSH扩展

  1. 在主机上打开VScode。
  2. 点击左侧活动栏的“扩展”图标（或按Ctrl+Shift+X）。
  3. 在搜索框中输入“Remote - SSH”。
  4. 找到由Microsoft发布的扩展，点击“安装”。

4.2 配置SSH连接信息

安装完成后，VScode左侧活动栏会出现一个“远程资源管理器”图标。点击它，然后点击SSH旁边的齿轮图标（配置），选择你的SSH配置文件（通常是C:\Users\你的用户名\.ssh\config）。

用文本编辑器打开这个config文件，添加如下配置：

Host UbuntuVM # 这是一个别名，方便记忆，可以自定义 HostName 192.168.1.100 # 替换为你的Ubuntu虚拟机IP地址 User developer # 替换为你的Ubuntu用户名 Port 22 # SSH端口，默认22。如果NAT转发到其他端口，这里要改，例如 Port 2222 IdentityFile ~/.ssh/id_rsa # 如果你使用密钥登录，指定私钥路径。密码登录可省略

参数解释：

  • Host：你给这个连接起的名字，在VScode里会显示这个。
  • HostName：最关键的一项，必须是虚拟机可被主机访问的IP。如果是NAT端口转发，这里填主机的IP（通常是127.0.0.1或localhost）。
  • Port：如果虚拟机SSH服务改了端口，或者你做了端口转发（例如将主机2222转发到虚拟机22），这里就填转发后的端口（2222）。
  • IdentityFile：指定私钥文件路径。配置后可以实现无密码登录。

4.3 发起连接并初始化远程环境

  1. 回到VScode的“远程资源管理器”，你应该能看到刚刚配置的UbuntuVM主机。
  2. 点击它右侧的“连接”图标（一个小窗口带加号）。
  3. 首次连接时，VScode会弹出一个新窗口，并在底部状态栏显示“正在连接...”。
  4. 如果使用密码登录，会弹出输入框让你输入用户密码。
  5. 连接成功后，VScode会开始“正在设置VS Code服务器”。这是它在你的Ubuntu虚拟机上自动下载并安装一个轻量级的vscode-server。这一步需要Ubuntu虚拟机能够访问外网。
  6. 安装完成后，你就进入了全新的远程窗口。注意看左下角，显示为“SSH: UbuntuVM”。

4.4 在远程环境中工作

现在，你所有的操作都在远程Ubuntu虚拟机上了。

  • 打开文件夹：点击“文件”->“打开文件夹”，你会看到Ubuntu虚拟机的文件系统，选择一个项目目录打开（例如/home/developer/projects）。
  • 使用终端：按Ctrl+`（反引号键）打开集成终端。这个终端直接运行在Ubuntu虚拟机里，你可以执行任何Linux命令。
  • 安装扩展：扩展分为“本地”和“远程”。在远程窗口安装的扩展（如Python、C++、Docker扩展）会实际安装在Ubuntu虚拟机上。你可以像在本地一样搜索并安装它们。
  • 编辑与运行代码：和你本地开发体验完全一致。当你运行或调试代码时，所有进程都在Ubuntu中执行。

5. 网络问题深度排查与解决方案

“不能建立到远程计算机的连接”是最高频的错误。其根源几乎100%在于网络不通或SSH服务不可达。请按照以下流程系统性排查。

5.1 排查流程表

步骤操作预期结果失败的可能原因与解决方案
1. 物理连通性在主机上打开命令提示符（CMD）或PowerShell，执行ping <虚拟机IP>收到来自虚拟机IP的回复，时间<1ms（局域网）无回复：虚拟机未开机、网络适配器未连接（在虚拟机软件中检查）、防火墙（主机或虚拟机）阻断了ICMP。先确保能ping通。
2. 端口可达性在主机上执行telnet <虚拟机IP> 22或ssh -v <用户名>@<虚拟机IP>Telnet显示空白屏幕（连接成功）或SSH输出调试信息直至提示输入密码连接被拒绝/超时：Ubuntu上SSH服务未运行（sudo systemctl start ssh）；防火墙（sudo ufw status查看，sudo ufw allow 22开放端口）；NAT模式未设置端口转发（需在虚拟机软件中配置）。
3. SSH配置验证在主机终端直接用SSH命令连接：ssh <用户名>@<虚拟机IP>能成功登录到Ubuntu虚拟机的命令行认证失败：用户名/密码错误；密钥配置错误（检查~/.ssh/authorized_keys权限必须是600）。权限问题：.ssh目录权限必须是700。
4. VScode配置核对检查VScode的SSH配置文件（~/.ssh/config）主机名、IP、端口、用户名、密钥路径均正确配置错误：IP地址错误（特别是NAT模式下用了虚拟机内网IP）；端口错误；密钥路径错误。
5. 主机防火墙检查Windows Defender防火墙或第三方防火墙允许VScode或SSH客户端通过被防火墙拦截：临时关闭防火墙测试，或在防火墙高级设置中为ssh.exe（或整个VScode）添加入站/出站规则。
6. 虚拟机网络模式确认虚拟机网络适配器设置桥接模式：虚拟机IP与主机同网段。
NAT模式：主机使用127.0.0.1+转发端口连接。		模式错误：桥接模式在某些公共Wi-Fi下可能失效，可切换为NAT并配置端口转发。

5.2 常见错误场景与解决

  • 场景一：使用NAT模式，但连接时IP填错了。

    • 错误：在VScode的config里，HostName填了虚拟机的内网IP（如192.168.122.xx）。
    • 解决：NAT模式下，主机访问虚拟机需要通过端口转发。HostName应填127.0.0.1，Port填你在虚拟机软件中设置的主机端口（如2222）。

  • 场景二：Ubuntu防火墙（UFW）阻止了SSH。

    • 排查：在Ubuntu终端执行sudo ufw status。如果状态是active，并且没有允许22端口，就会阻止连接。
    • 解决：sudo ufw allow 22然后sudo ufw reload。或者，对于开发环境，可以暂时禁用UFW：sudo ufw disable（不推荐长期禁用）。

  • 场景三：SSH服务监听地址限制。

    • 排查：默认sshd监听所有接口。检查配置文件/etc/ssh/sshd_config，看是否有ListenAddress行，并只绑定了127.0.0.1。这会导致只允许本地连接。
    • 解决：注释掉ListenAddress行（在前面加#），或改为ListenAddress 0.0.0.0。然后重启服务：sudo systemctl restart sshd。

  • 场景四：首次连接卡在“正在下载VS Code服务器”。

    • 原因：Ubuntu虚拟机无法访问GitHub等外网，无法下载vscode-server的安装包。
    • 解决：
      1. 手动下载：在错误信息中或VScode输出面板（“视图”->“输出”，选择“Remote-SSH”）里找到需要下载的vscode-server的commit id。然后通过其他能上网的机器，从https://update.code.visualstudio.com/commit:${COMMIT_ID}/server-linux-x64/stable下载对应文件。将其拷贝到Ubuntu的~/.vscode-server/bin/${COMMIT_ID}目录下，并解压（可能需要重命名）。
      2. 使用代理：如果主机有网络代理，可以在VScode的SSH配置文件中为这个Host配置代理。在~/.ssh/config中添加：
        Host UbuntuVM ... ProxyCommand connect -H http://your-proxy:port %h %p
        （需要安装connect工具）。

6. 高级配置与效率提升技巧

稳定连接只是第一步，高效工作才是目的。下面这些技巧能极大提升你的远程开发体验。

6.1 多配置管理与快速切换

如果你需要连接多个不同的远程服务器或虚拟机，可以在~/.ssh/config中配置多个Host块。

Host UbuntuVM-ProjectA HostName 192.168.1.100 User dev_a Host UbuntuVM-ProjectB HostName 192.168.1.101 User dev_b Port 2222 IdentityFile ~/.ssh/id_rsa_project_b Host AliyunECS HostName ecs-ip-address User root IdentityFile ~/.ssh/aliyun.pem

在VScode远程资源管理器中，它们会并列显示，一键切换。

6.2 保持连接稳定与自动重连

网络波动可能导致连接中断。可以修改SSH客户端配置，增加保活和重试。

在~/.ssh/config的对应Host或全局设置（最前面）添加：

ServerAliveInterval 60 ServerAliveCountMax 3

这表示客户端每60秒向服务器发送一个保活包，如果连续3次（即3分钟）没有收到响应，则认为连接已断开。VScode在检测到断开后通常会尝试自动重连。

6.3 在远程环境中使用Docker

这是远程开发的“终极形态”之一。你可以在Ubuntu虚拟机内安装Docker，然后在VScode中安装“Dev Containers”扩展。这样，你可以为每个项目创建一个独立的Docker容器作为开发环境，通过VScode直接连接到容器内部进行开发，实现极致的环境隔离与复现。

  1. 在远程Ubuntu上安装Docker。
  2. 在远程VScode窗口中安装“Dev Containers”扩展。
  3. 在项目根目录创建.devcontainer/devcontainer.json配置文件，定义你的开发容器镜像、工具、扩展等。
  4. 重新打开项目时，VScode会提示“在容器中重新打开”，之后所有操作都在这个纯净的容器内进行。

6.4 文件传输与同步

虽然你直接在远程文件系统上编辑，但有时也需要与主机互传文件。

  • VScode内置：远程连接后，你可以直接通过VScode的资源管理器拖拽文件，或者使用右键的“上传”、“下载”功能。这背后使用的是SSH的SFTP协议。
  • 命令行SCP：在主机终端使用scp命令，语法与cp类似：
    # 从主机复制到远程 scp ./local-file.txt developer@192.168.1.100:/home/developer/ # 从远程复制到主机 scp developer@192.168.1.100:/home/developer/remote-file.txt ./

6.5 性能调优

如果感觉远程界面响应有些延迟，可以尝试：

  1. 关闭不必要的扩展：有些扩展在远程模式下可能不兼容或影响性能，可以在远程窗口禁用它们。
  2. 调整VScode设置：在远程窗口的“设置”中，搜索“Files: Watcher Exclude”，添加一些不需要实时监控的大文件或目录模式（如**/node_modules/**,**/.git/**），减少文件系统监听的开销。
  3. 确保虚拟机资源充足：为虚拟机分配足够的内存和CPU核心，特别是当你需要在其中运行数据库、消息队列等后端服务时。

7. 避坑指南与疑难杂症实录

这里记录了我个人和团队在长期使用中踩过的一些“深坑”，以及最终的解决方案。

坑1：连接成功，但打开文件夹或终端极慢，甚至超时。

  • 现象：SSH连接很快，但进入远程窗口后，任何操作都卡顿。
  • 排查：这通常不是网络问题，而是远程服务器（虚拟机）上的vscode-server或其某个扩展在尝试进行网络请求（如检查更新、获取远程资源）时被阻塞。
  • 解决：
    • 检查Ubuntu虚拟机的DNS配置（cat /etc/resolv.conf），确保它能正确解析域名。可以尝试修改为公共DNS，如8.8.8.8。
    • 在VScode远程设置中（设置 -> Remote.SSH），尝试开启或关闭Remote.SSH: Use Local Server选项，看看是否有变化。
    • 最根本的，检查Ubuntu虚拟机的网络，确保它能正常访问互联网（ping 8.8.8.8,curl -I https://github.com）。

坑2：重装系统或更换用户后，远程连接报权限错误。

  • 现象：错误信息提及vscode-server目录权限问题，或者.vscode-server目录下的文件损坏。
  • 解决：这是最彻底的清理方法——手动删除远程服务器上的VScode相关目录，让扩展重新安装。
    1. 通过其他方式（如虚拟机控制台或另一个SSH客户端）登录Ubuntu。
    2. 删除用户主目录下的相关文件夹：
      rm -rf ~/.vscode-server rm -rf ~/.vscode-server-insiders # 如果使用Insiders版本
    3. 重新从VScode发起连接，它会重新下载安装服务器端。

坑3：密钥登录配置正确，但依然要求输入密码。

  • 排查：
    1. 在主机执行ssh -v user@host，查看详细输出，看它尝试了哪些认证方式。
    2. 检查Ubuntu上~/.ssh/authorized_keys文件的权限，必须是600，所属用户和组正确。
    3. 检查Ubuntu上/etc/ssh/sshd_config中，是否设置了PasswordAuthentication yes和PubkeyAuthentication yes。修改后需重启sshd服务。
    4. 一个隐蔽的坑：Windows上使用Pageant（PuTTY的认证代理）管理密钥时，VScode的SSH扩展可能无法直接使用。建议使用OpenSSH格式的密钥，并通过ssh-add命令将私钥添加到Windows自带的OpenSSH认证代理中。

坑4：从公司网络切换到家庭网络后，连接失败。

  • 原因：虚拟机IP地址变了（特别是桥接模式下，DHCP分配了新IP）。
  • 解决：
    • 动态DNS：对于桥接模式，可以考虑在路由器或虚拟机内设置静态IP（DHCP保留），避免IP变化。
    • 使用主机名：如果网络支持mDNS（如很多家庭路由器），可以在Ubuntu上安装avahi-daemon，然后就可以用hostname.local（如ubuntu-vm.local）来连接，代替IP地址。
    • 更新配置文件：最直接的方法，每次IP变，就去更新~/.ssh/config文件中的HostName。

配置VScode远程连接Ubuntu虚拟机，本质上是在搭建一个无缝的跨平台开发桥梁。一旦打通，你会发现自己再也回不去那种割裂的开发方式了。所有的环境依赖、编译工具链、运行时都规整在虚拟机里，而你可以用自己最趁手的本地机器进行编码。这个组合，对于需要Linux环境但又离不开Windows/macOS生态的开发者来说，生产力提升是巨大的。关键在于理解SSH这个核心纽带，并耐心完成初始的网络配置。希望这篇详尽的指南能帮你一次成功，少走弯路。如果在实践中遇到新的问题，不妨多观察VScode的输出窗口和Ubuntu的系统日志（journalctl -u ssh -f），那里通常藏着答案。

编程学习 学习日记 实战经验
← 返回列表