1. 项目概述为什么我们需要VScode远程连接Ubuntu虚拟机作为一名常年穿梭于Windows、Linux和各类云服务器之间的开发者我深知在不同环境间切换编码的痛苦。你可能在Windows上享受着熟悉的操作界面和丰富的办公软件但项目的编译、部署和运行环境却要求是Linux特别是Ubuntu。直接在Windows上搞个WSLWindows Subsystem for Linux是个选择但对于需要完整Linux内核特性、特定虚拟机网络拓扑比如搭建分布式集群或者资源隔离的场景在VMware或VirtualBox里跑一个Ubuntu虚拟机依然是更经典、更可控的方案。问题来了你愿意在虚拟机那小小的窗口里用着可能不太顺手的终端编辑器如vim、nano写代码吗或者频繁地在主机和虚拟机之间拖拽文件效率太低下了。这时VScode的“远程开发”功能就成了救星。它允许你将本地的VScode变成一个纯粹的“前端界面”而所有的代码编辑、终端操作、插件运行都实际发生在远程的Ubuntu虚拟机中。你获得的是本地VScode的流畅体验和强大生态同时享受Ubuntu原生环境的纯粹与兼容性。这不仅仅是连接更是一种开发范式的转变将本地IDE的便利性与远程服务器的能力无缝融合。简单来说这个方案解决了几个核心痛点第一环境一致性保证开发、测试、生产环境统一第二性能隔离编译等重负载任务在虚拟机内进行不影响主机第三体验提升在熟悉的VScode里操作一切无需适应虚拟机内的GUI或纯终端。接下来我将手把手带你完成从零开始的配置并分享我趟过的所有坑和最终沉淀下来的稳定方案。2. 核心原理与方案选型SSH为何是唯一推荐要实现VScode远程连接底层通信协议是关键。你可能听过一些其他方式比如利用VScode的“隧道”功能或者一些第三方插件但经过多年实践SSHSecure Shell是唯一稳定、安全、高效且官方全力支持的标准方案。VScode的“Remote - SSH”扩展就是围绕SSH构建的。2.1 为什么是SSH安全性SSH天生为加密远程登录而设计所有传输数据包括密码、命令、文件都经过加密避免了在局域网甚至公网上明文传输的敏感信息泄露风险。这是任何生产级开发都必须考虑的基础。普遍性与稳定性SSH是Linux/Unix系统的标准服务Ubuntu默认安装并可以轻松开启。其协议成熟网络兼容性极好穿透各种NAT和防火墙的成功率相对较高尤其是在配置了端口转发的情况下。功能完整性SSH不仅仅是一个登录通道。它支持端口转发用于调试、SFTP用于文件传输而VScode Remote正是利用SSH通道建立了一个稳定的、支持多种服务的连接使得代码智能感知、插件安装、终端访问等都能流畅进行。官方支持与生态微软官方开发的“Remote - SSH”扩展体验最为完善更新及时与VScode核心功能集成度最高。它本质上是一个“SSH客户端远程环境管理器”而不是一个简单的文件同步工具。2.2 与其他方式的对比直接使用虚拟机共享文件夹在虚拟机软件中设置共享文件夹然后在主机VScode中打开这个共享目录。这种方式的问题是文件操作尤其是大量小文件的I/O性能损耗大并且文件权限Linux的rwx在Windows共享下管理混乱容易导致脚本无法执行等问题。第三方同步插件需要双向监控和同步文件配置复杂且实时性难以保证容易产生冲突。RDP或VNC连接虚拟机桌面这相当于远程桌面会传输整个GUI界面带宽占用高延迟明显且你仍然是在虚拟机的桌面环境里用一个可能不那么好用的编辑器。因此SSH方案是性能和体验的最优解。它让你感觉像是在本地开发但所有计算都在远程。2.3 整体连接架构图逻辑描述理解连接架构有助于排查问题主机Windows/Mac运行VScode并安装了“Remote - SSH”扩展。扩展充当SSH客户端。网络桥梁虚拟机网络需要配置为“桥接模式”或“NAT模式端口转发”确保主机能通过IP地址访问到虚拟机的22号端口SSH默认端口。客体机Ubuntu虚拟机运行sshd服务监听22端口接受来自主机的SSH连接。连接建立后VScode扩展会在客体机上自动安装一个轻量级的“VS Code Server”这个Server负责与主机上的VScode前端通信执行具体的编辑、插件等命令。整个过程中你的代码文件始终只存在于Ubuntu虚拟机中VScode界面只是它们的“镜像”视图。3. 环境准备虚拟机、Ubuntu与SSH服务配置工欲善其事必先利其器。稳定的连接始于一个正确配置的基础环境。3.1 虚拟机与Ubuntu安装要点如果你已经有一个可用的Ubuntu虚拟机可以跳过此步但请务必核对网络配置。虚拟机软件选择VMware Workstation Player免费或 VirtualBox免费均可。VMware在性能和网络配置上通常更简单稳定一些本文以VMware为例但原理通用。Ubuntu镜像下载建议从Ubuntu官网下载最新的LTS版本如22.04 LTS。LTS版本提供长期支持更稳定。虚拟机创建关键设置网络适配器这是重中之重。创建时或创建后在虚拟机设置中将网络连接设置为“桥接模式”。桥接模式会让虚拟机从你的家庭路由器获取一个和主机同网段的独立IP地址如192.168.1.x就像一台真实的新电脑接入了你的局域网。这是最推荐的方式连接最简单。如果无法使用桥接例如公司网络有限制则使用“NAT模式”。在NAT模式下虚拟机处于一个虚拟子网中主机可以访问它但外部网络不能直接访问虚拟机。此时你必须在虚拟机软件中设置“端口转发”将主机的某个端口如2222转发到虚拟机的22端口。具体设置在VMware的“编辑”-“虚拟网络编辑器”中找到NAT模式的网络点击“NAT设置”添加一条转发规则。内存与CPU根据你的开发需求分配建议至少2核CPU4GB内存。运行VScode Server本身需要一定资源。安装Ubuntu按照向导安装建议选择“最小化安装”以减少不必要的软件包。务必记住你设置的用户名和密码。3.2 Ubuntu系统内SSH服务安装与配置Ubuntu桌面版默认可能没有安装SSH服务器。打开终端在Ubuntu虚拟机内按CtrlAltT打开终端。安装OpenSSH服务器sudo apt update sudo apt install openssh-server检查服务状态安装后SSH服务通常会自动启动。可以通过以下命令检查sudo systemctl status ssh如果看到active (running)说明服务正在运行。如果没有运行使用sudo systemctl start ssh启动它并使用sudo systemctl enable ssh设置开机自启。可选但推荐配置密钥登录使用密码登录每次都需要输入且安全性稍弱。配置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为你的虚拟机IPdeveloper为你的用户名 ssh-copy-id developer192.168.1.100如果提示命令不存在可以手动操作先将主机~/.ssh/id_rsa.pub文件内容复制出来然后在Ubuntu虚拟机中执行mkdir -p ~/.ssh echo “你复制的公钥内容” ~/.ssh/authorized_keys chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys获取虚拟机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扩展在主机上打开VScode。点击左侧活动栏的“扩展”图标或按CtrlShiftX。在搜索框中输入“Remote - SSH”。找到由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 发起连接并初始化远程环境回到VScode的“远程资源管理器”你应该能看到刚刚配置的UbuntuVM主机。点击它右侧的“连接”图标一个小窗口带加号。首次连接时VScode会弹出一个新窗口并在底部状态栏显示“正在连接...”。如果使用密码登录会弹出输入框让你输入用户密码。连接成功后VScode会开始“正在设置VS Code服务器”。这是它在你的Ubuntu虚拟机上自动下载并安装一个轻量级的vscode-server。这一步需要Ubuntu虚拟机能够访问外网。安装完成后你就进入了全新的远程窗口。注意看左下角显示为“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 用户名虚拟机IPTelnet显示空白屏幕连接成功或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.1Port填你在虚拟机软件中设置的主机端口如2222。场景二Ubuntu防火墙UFW阻止了SSH。排查在Ubuntu终端执行sudo ufw status。如果状态是active并且没有允许22端口就会阻止连接。解决sudo ufw allow 22然后sudo ufw reload。或者对于开发环境可以暂时禁用UFWsudo 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的安装包。解决手动下载在错误信息中或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}目录下并解压可能需要重命名。使用代理如果主机有网络代理可以在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直接连接到容器内部进行开发实现极致的环境隔离与复现。在远程Ubuntu上安装Docker。在远程VScode窗口中安装“Dev Containers”扩展。在项目根目录创建.devcontainer/devcontainer.json配置文件定义你的开发容器镜像、工具、扩展等。重新打开项目时VScode会提示“在容器中重新打开”之后所有操作都在这个纯净的容器内进行。6.4 文件传输与同步虽然你直接在远程文件系统上编辑但有时也需要与主机互传文件。VScode内置远程连接后你可以直接通过VScode的资源管理器拖拽文件或者使用右键的“上传”、“下载”功能。这背后使用的是SSH的SFTP协议。命令行SCP在主机终端使用scp命令语法与cp类似# 从主机复制到远程 scp ./local-file.txt developer192.168.1.100:/home/developer/ # 从远程复制到主机 scp developer192.168.1.100:/home/developer/remote-file.txt ./6.5 性能调优如果感觉远程界面响应有些延迟可以尝试关闭不必要的扩展有些扩展在远程模式下可能不兼容或影响性能可以在远程窗口禁用它们。调整VScode设置在远程窗口的“设置”中搜索“Files: Watcher Exclude”添加一些不需要实时监控的大文件或目录模式如**/node_modules/**,**/.git/**减少文件系统监听的开销。确保虚拟机资源充足为虚拟机分配足够的内存和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相关目录让扩展重新安装。通过其他方式如虚拟机控制台或另一个SSH客户端登录Ubuntu。删除用户主目录下的相关文件夹rm -rf ~/.vscode-server rm -rf ~/.vscode-server-insiders # 如果使用Insiders版本重新从VScode发起连接它会重新下载安装服务器端。坑3密钥登录配置正确但依然要求输入密码。排查在主机执行ssh -v userhost查看详细输出看它尝试了哪些认证方式。检查Ubuntu上~/.ssh/authorized_keys文件的权限必须是600所属用户和组正确。检查Ubuntu上/etc/ssh/sshd_config中是否设置了PasswordAuthentication yes和PubkeyAuthentication yes。修改后需重启sshd服务。一个隐蔽的坑Windows上使用PageantPuTTY的认证代理管理密钥时VScode的SSH扩展可能无法直接使用。建议使用OpenSSH格式的密钥并通过ssh-add命令将私钥添加到Windows自带的OpenSSH认证代理中。坑4从公司网络切换到家庭网络后连接失败。原因虚拟机IP地址变了特别是桥接模式下DHCP分配了新IP。解决动态DNS对于桥接模式可以考虑在路由器或虚拟机内设置静态IPDHCP保留避免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那里通常藏着答案。