作为一个常年要在本地写代码、服务器上跑训练的人我可以很负责任地说VSCode 的 Remote-SSH 功能基本是目前远程开发体验里最“无痛”的方案。不管你是刚接触 Linux 服务器的新手还是已经在 Xshell、PuTTY、WinSCP 之间反复横跳的老手这篇文章都适合你。我会从“为什么推荐用 VSCode 连接服务器”讲起一步步带你走通环境准备、SSH 密钥配置、config 文件写法再到连接后的远程开发技巧和常见报错排查全程按我的实操经验来不绕弯子。如果你只是想在服务器上改个配置文件那用命令行工具就够了。但如果你要在服务器上写 Python 脚本、调 C 程序、跑深度学习实验还要边看代码边调试继续在纯终端里用 vim 就太折磨人了。VSCode 远程连接服务器的核心价值就是让“本地写代码”和“服务器运行”彻底一体化你在 VSCode 里打开的文件夹是服务器上的终端是服务器上的Python 解释器是服务器上的代码补全、断点调试、Git 面板也都是针对远程代码的。这种体验一旦用顺了你大概率不会再想回到“本地写完后上传再跑”的老流程。1. 内容整体设计与思路拆解1.1 远程开发的传统痛点先聊几句我自己的经历。早几年我做服务器上的开发用的是“Xshell 开终端 WinSCP 传文件”的组合流程大概是本地改代码上传终端里跑看报错再回本地改再上传……循环往复。遇到数据量大的工程本地代码和服务器代码版本不一致是常有的事搞着搞着就忘了服务器上跑的是哪一版非常崩溃。后来也用过 PyCharm 的远程解释器功能确实强但资源占用高配置相对繁琐而且远程调试某些类型的项目还是有点“重”。VSCode 的 Remote-SSH 之所以能成为大众选择核心在于它把远程开发做成了“本地文件夹直接映射到远程”你不会感觉到代码是在另一台机器上编辑、跳转、搜索、重构、版本管理全是本地手感。这就把传统方案里“上传—运行—修改”这条割裂链路压缩成了“直接改—直接跑”。1.2 Remote-SSH 的核心原理Remote-SSH 的工作机制一句话概括就是你本地 VSCode 是“客户端”远程服务器上会自动部署一个“VSCode Server”两者通过 SSH 通道通信。你在编辑器里看到的文件内容来自远端键盘输入、鼠标点击、代码补全请求都通过网络传给远端 Server处理结果再传回来显示在本地界面上。这里有两个容易被新手误解的地方。第一插件不是全都能在远程用。VSCode 的插件分两类一类是“本地 UI 插件”和“工作区插件”。Remote-SSH 场景下有的插件需要装在远程比如 Python、C/C 扩展有的只需装本地比如主题、快捷键类。当你连接服务器后VSCode 会智能提示“这个插件建议安装在远程”问你是否安装到远程环境。实际开发中我一般把 Python、Pylance、C/C、GitLens 这类与代码相关的插件都装在远程主题和 JSON 工具之类留在本地。第二Remote-SSH 需要服务器能正常运行 vscode-server。这个 server 是 VSCode 自动下载到用户目录下的~/.vscode-server里的。如果你的服务器无法访问微软的下载地址或者服务器系统比较老旧就会出现连接卡在“Installing VS Code Server”的问题。这个我后面会专门讲怎么处理。1.3 什么场景适合用它Remote-SSH 适合绝大多数“计算在服务器、开发在本地”的场景比如深度学习训练服务器上有 GPU本地没有代码在服务器上直接跑后端服务开发部署环境是 Linux本机是 Windows/macOS直接在 Linux 上写代码避免环境不一致大数据处理数据文件大本地磁盘放不下服务器上直接操作多台服务器管理通过 config 文件配置多台机器一键切换不用记 IP 和用户名。不过也得说句实话如果你的服务器带宽特别差、延迟特别高几百毫秒甚至更高Remote-SSH 的体验会明显下降毕竟每个光标移动都要走一次网络。还有如果你只是临时上去敲几条命令直接 SSH 登录终端就够了没必要开 VSCode。2. 环境准备与前置配置2.1 准备 VSCode 与 Remote-SSH 插件这一步没什么难度但我还是想强调几个细节因为真有不少人卡在这。VSCode 建议装最新稳定版Go 到官网下载对应平台的安装包。Windows 用户安装时有一个选项是“添加到 PATH”建议勾上。这么做的好处是你可以在任意终端里直接用code命令启动 VSCode后面有些自动化操作会方便很多。安装完 VSCode 后打开扩展面板搜索Remote - SSH注意认准发布者是 Microsoft 的那个。安装完它会提示你重新加载然后左侧会出现一个“远程资源管理器”图标通常是一台显示器带一根线的样子。这里要提醒一句Remote-SSH 插件是一个“扩展包”它内部会依赖Remote - SSH: Editing Configuration Files、Remote Explorer等子组件安装时它会自动一并装上不用手动单独安装。2.2 确认 SSH 连得上在打开 VSCode 之前我强烈建议你先在本地终端里手工验证一次 SSH 能否正常连上服务器。这个习惯能帮你把“SSH 问题”和“VSCode 问题”区分开排查起来省很多时间。Windows 用户直接用 PowerShell 或 CMDmacOS/Linux 用户用自带终端命令是ssh 用户名服务器IP -p 端口号比如ssh root192.168.1.100 -p 22如果不带端口SSH 默认走 22 端口。如果你的服务器用的是自定义端口比如 2222就必须要加-p 2222。这一步能成功登录说明网络、账号、端口都没问题接下来在 VSCode 里连接时如果还失败那大概率是 VSCode 配置层面的问题。还需要确认一下服务器有没有安装 SSH 服务端。多数云服务器镜像默认带但有些精简系统会不带。如果本地ssh命令提示Connection refused可以先到服务器控制台或者让管理员执行systemctl status sshd如果没有就安装一下Ubuntu/Debian 系执行sudo apt install openssh-serverCentOS/RHEL 系执行sudo yum install openssh-server。装完启动并设置开机自启sudo systemctl start sshd sudo systemctl enable sshd2.3 准备好连接信息开始连接前你需要明确这样几项信息服务器 IP 地址或域名SSH 端口号默认 22登录用户名认证方式密码还是密钥推荐密钥。如果是公司或实验室的服务器端口、用户名这些一般由管理员分配。如果是自己的云服务器IP 和控制台密码在服务商后台都能看到。这里多说一句不管是谁的服务器密码登录都不如密钥登录安全而且密钥登录还能省去每次输入密码的麻烦后面我会给出完整配置方法。3. 实操过程与核心环节实现3.1 用图形界面发起第一次连接现在打开 VSCode点击左侧的远程资源管理器图标你会看到 “REMOTE EXPLORER” 面板里面有一个下拉框可以选 SSH Targets。点击面板上的“Connect to Host”或者按 F1 输入Remote-SSH: Connect to Host...这时 VSCode 会弹出一个输入框让你输入 SSH 连接命令格式和终端里一样用户名服务器IP -p 端口号比如root192.168.1.100 -p 22回车后 VSCode 会弹出选择窗口让你选择这个连接配置保存到哪个 SSH config 文件里。新手直接选默认的第一个路径即可一般位于~/.ssh/configWindows 下是C:\Users\你的用户名\.ssh\configmacOS/Linux 下是/home/你的用户名/.ssh/config。选完后 VSCode 开始连接第一次连接会在服务器端下载并安装vscode-server这步可能耗时几十秒到几分钟取决于服务器下载速度。出现提示时选择操作系统的类型通常 Linux然后输入密码。密码验证通过后VSCode 底部状态栏会变成绿色的“SSH: 服务器IP”左下角显示远程连接状态底部会打开一个新的终端这个终端默认就是登录到远程服务器上的。到这一步你就已经成功在 VSCode 里打开了远程服务器。点击左侧“资源管理器”选择“打开文件夹”输入服务器上的路径比如/home/ubuntu/project就能直接以该目录作为工作目录开始开发。3.2 SSH config 配置文件详解直接通过弹窗输入连接信息虽然方便但如果你经常连接多台服务器还是建议在 config 文件里把每台机器定义好以后一键选择不用每次敲这么长串命令。打开 config 文件的方式有两种一是从远程资源管理器面板里点“齿轮”图标选择“SSH 配置文件”二是按 F1 执行Remote-SSH: Open SSH Configuration File选择之前那个默认路径。一个典型的 config 文件长这样Host my-server HostName 192.168.1.100 User root Port 22 IdentityFile ~/.ssh/id_rsa各行的含义Host这个连接在 VSCode 里显示的别名可以随便起比如my-server方便记忆HostName实际的 IP 地址或域名User登录用户名PortSSH 端口默认 22如果服务器改了端口这里必须写对IdentityFile私钥文件路径。如果你已经在服务器上配置了密钥登录建议写上这一行这样连接时会自动使用密钥认证不用输入密码。没有配置密钥的第一次可以把这行先注释掉用密码登录。配置多台服务器时只需要复制多份块改掉 Host 名称和 HostName 就行。保存后回到远程资源管理器面板刷新一下就能看到所有配置好的目标主机了。之后点击某台主机选择“在当前窗口连接”或者“在新窗口连接”就能直接建立 SSH 会话。IdentityFile这个路径在 Windows 上要特别注意。如果你用的是 OpenSSH 生成的密钥默认路径是C:\Users\你的用户名\.ssh\id_rsa。在 config 文件里Windows 路径可以写成IdentityFile C:\Users\你的用户名\.ssh\id_rsa也可以写正斜杠IdentityFile C:/Users/你的用户名/.ssh/id_rsa实测两种写法都行但如果你把路径写在双引号里并带了反斜杠可能因为转义问题导致解析失败建议直接用正斜杠最省事。3.3 配置免密登录密钥登录每次连接都输入密码不是不行但稍微有点影响效率尤其是 VSCode 连接后还要重连、加载远程扩展、同步文件密码输多了就容易烦。更关键的是密码认证在服务器上被暴力破解的风险远大于密钥认证。所以我建议所有账号都换成密钥登录。操作分三步第一步在本机生成密钥对。打开本地终端执行ssh-keygen -t rsa -b 4096一路回车即可默认会生成到~/.ssh/id_rsa私钥和~/.ssh/id_rsa.pub公钥。如果你电脑上已经有密钥文件不想覆盖可以换一个文件名比如ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_server后面把私钥路径填到 config 的 IdentityFile 里就行。第二步把公钥内容添加到服务器的~/.ssh/authorized_keys文件中。最简单的方式是用ssh-copy-id命令ssh-copy-id 用户名服务器IP -p 端口号它会要求你输入一次密码然后把本机的公钥自动追加到服务器的authorized_keys里。如果ssh-copy-id不可用Windows OpenSSH 通常自带就手工操作先查看公钥内容cat ~/.ssh/id_rsa.pub复制输出内容然后 SSH 登录服务器执行mkdir -p ~/.ssh chmod 700 ~/.ssh echo 粘贴你的公钥内容 ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys第三步是关键权限必须对。很多新手卡在“明明公钥加了登录还是要密码”十有八九是权限问题。服务器上的~/.ssh目录必须是 700authorized_keys文件必须是 600~目录本身也不能被组用户或其他人写。简单说执行完上述命令后你的目录权限应该是drwx------ 2 user user 4096 ... .ssh -rw------- 1 user user 800 ... authorized_keys如果权限不对在服务器上执行chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys修正。之后退出重新连接就不需要密码了。3.4 连接后的远程开发设置连接成功后你会发现 VSCode 的“扩展”面板变成了两个分区一个是“本地 - SSH: 服务器IP”一个是“已安装”。这个设计很关键你在远程最常用的语言包、代码提示、调试器要装到远程那一栏里。以 Python 开发为例连接服务器后建议在远程环境里安装Python微软官方扩展自带调试和智能感知Pylance做代码补全和类型检查体验提升非常明显Jupyter如果你要在服务器上跑 notebookGitLens查看 Git 历史、责任归属装本地也可以但远程装效果更好Remote Explorer 里相关的 SSH 扩展比如 Remote-SSH 编辑器用于修改 config 文件装完扩展VSCode 通常会自动重新加载。之后按CtrlShiftP打开命令面板执行Python: Select Interpreter选择服务器上的 Python 路径。如果你服务器上用的是conda环境也能在下拉框里直接选到VSCode 会自动检测~/anaconda3/envs/xxx/bin/python这样的路径。界面左下角还可以设置端口转发。比如你在服务器上启动了 Jupyter Notebook默认监听在 8888 端口那么你在 VSCode 的“端口”面板里添加8888VSCode 会通过 SSH 隧道自动映射到本地浏览器访问http://localhost:8888就能直接打开服务器上的服务。这个功能对调试 Web 服务、TensorBoard、Grafana 这类图形化工具非常实用强烈建议记住。4. 常见问题与排查技巧实录这一部分我把自己和周边人经常踩的坑整理一下按“症状—原因—解决”的逻辑做成速查表方便你直接定位。4.1 浏览器打开出现“此连接已被阻止”怎么办有些读者在连接服务器后会遇到这样的情况自己在本地用浏览器访问http://localhost:8888比如 Jupyter Notebook或者访问某些内网服务时页面弹出英文或中文提示“此连接已被阻止因为它是公共页面发起的旨在连接到您本地网络上的设备或服务器。”这个问题的本质不是 VSCode 连不上服务器而是浏览器的一种本地网络安全保护机制在起作用。浏览器检测到当前页面的来源是公网或者是配置了公网访问的网页但它尝试访问的地址却是用户本地的localhost或局域网地址浏览器认为这可能存在跨域请求本地网络的风险于是直接拦截了。解决办法比较简单这种提示多出现在浏览器访问本地端口转发地址时你只要在浏览器弹出的拦截页里点击“继续访问”之类的按钮即可。如果你确定这个端口是安全的也可以在连接服务器时不走浏览器映射而是直接用 VSCode 内置的“简单浏览器”打开localhost:8888它不受这个拦截逻辑影响。另外如果你根本不需要浏览器访问服务这个提示可以忽略不影响 SSH 连接和代码编辑。还有一种情况是你使用的是浏览器版 VSCodevscode.dev 或类似在线工具它尝试连接你本地网络的服务器时也可能触发类似提示。这类在线工作区连接本地或远程服务器本质上还是走浏览器安全沙箱策略比较严格。我的建议是日常开发请使用桌面版 VSCode Remote-SSH浏览器的机制限制太多只适合应急看代码不适合做正经远程开发。4.2 常见问题速查表症状可能原因排查与解决连接超时网络不通 / 防火墙拦了端口 / SSH 服务未启动先ping 服务器IP再telnet 服务器IP 22或nc -vz 服务器IP 22检查端口是否开放用本地终端ssh 用户名IP -p 端口排除问题提示 Permission denied (publickey,password)用户名或密码错 / 服务器禁止密码登录 / 密钥不对确认账号密码查看服务器/etc/ssh/sshd_config里PasswordAuthentication是否为 yes如果用密钥确认公钥内容已追加到authorized_keys私钥路径是否填对连接时反复要求输入密码密钥登录未配置成功 / config 里没写 IdentityFile按 3.3 步骤重新配置密钥确保~/.ssh和authorized_keys权限正确本地打开 config 文件检查 IdentityFile 是否指向正确私钥卡在 “Installing VS Code Server”服务器无法访问微软下载地址 / 网络慢 / 服务器系统过旧查看 Remote-SSH 输出日志输出面板选 Remote-SSH在服务器上检查~/.vscode-server是否已有内容网络问题可在服务器配置代理或更换网络环境系统过旧可考虑升级 glibc 或手动安装 server 包远程扩展装不上或总是装失败服务器网络受限 / 扩展版本不兼容在扩展面板选择“SSH: 服务器IP”后再搜索扩展安装如果网络差可以用 VSCode 的Extensions: Install from VSIX手动安装离线包中文显示乱码服务器编码问题在 VSCode 设置中搜索files.encoding改为utf8或在服务器上执行echo export LANGen_US.UTF-8 ~/.bashrc后重开终端打开文件夹后没有代码提示对应语言扩展装到了本地没装到远程连上服务器后按CtrlShiftP执行Remote-SSH: Install Local Extensions in SSH: 服务器IP把需要的扩展安装到远程状态栏显示远程但无法跳转定义语言服务器未启动 / 解释器未选择对 Python执行Python: Select Interpreter选择服务器解释器对 C/C确认安装了 C/C 扩展且 IntelliSense 配置正确4.3 “vscode-server 安装失败”的排查思路这句话我在各种论坛里看过无数次包括我自己的同事也常被这个问题卡住。Connect 到服务器后VSCode 会在远端自动部署vscode-server如果这个组件没有成功安装整个远程功能就是废的。一个非常有效的排查方法打开 VSCode 的“输出”面板把输出通道切到 “Remote-SSH”你会看到详细日志。常见的报错信息有两种一是下载超时二是tar解压失败。如果确定是服务器网络下载不了实测最直接的办法是先尝试换一个网络环境重连如果服务器在国内且下载微软服务器实在太慢也可以手动从微软镜像地址下载vscode-server-linux-x64.tar.gz对应的版本压缩包放到~/.vscode-server/bin/commit-id/目录下手动解压。这个操作稍微进阶一点新手如果没有把握还是优先换网络环境试。还有一种隐蔽的原因是服务器的系统时间不对。SSH 握手本身对时间偏差敏感如果服务器时间比真实时间差很多连接会直接失败而且报错信息看起来像网络问题。解决办法是同步时间比如执行sudo ntpdate ntp.aliyun.com或sudo timedatectl set-ntp true再重试。4.4 “每次打开 VSCode 都要重新选择项目”的问题有位读者问过为什么每次打开 VSCode 都要重新打开远程文件夹不能记住上次的项目。这其实只是设置问题。VSCode 默认情况下当你点击某个 SSH 主机连接进去后如果没有通过“文件-打开文件夹”选择工作目录那它就是一个空窗口下一次连接自然也要重新选。解决办法是在 config 文件里给 Host 加上一行Host my-server HostName 192.168.1.100 User root Port 22 RemoteHome /rootRemoteHome的作用是告诉 VSCode连接后默认把远程用户的 home 目录作为起点。如果你想要更精确让 VSCode 每次连接后自动打开指定目录可以用 VSCode 的“工作区”功能连上服务器后选择“文件-将工作区另存为”把工作区文件保存到远程目录里。下次直接打开这个.code-workspace文件工作区、打开的文件、打开的扩展就都恢复了。另外一个实用小技巧在 VSCode 里按CtrlR或CmdR可以快速重新打开上一次的远程窗口不用从远程资源管理器重新点。4.5 多台服务器时怎么管理连接配置我在本地维护了一份~/.ssh/config里面配置了开发机、GPU 服务器、跳板机等多台机器。配置多了之后最重要的是给每台机器起一个容易辨认的别名别用一串 IP 当 Host 名不然过几天你自己都不知道连的是哪台。常用的管理技巧分组config 文件里可以用#注释分隔不同项目复用跳板机如果你的服务器在安全组后面只有通过跳板机才能访问可以在 Host 配置里加ProxyJump字段Host server-internal HostName 10.0.0.5 User ubuntu ProxyJump jump-server这样你本地只需要能连到jump-serverVSCode 就会自动通过跳板机再连到内网服务器省去手动开隧道的麻烦。5. 进阶技巧与效率提升5.1 端口转发把服务器上的服务映射到本地前面简单提过VSCode 的“端口”PORTS面板支持自动转发。这里我再细说一下因为它的使用场景比很多人想象中要广。当你在远程终端里运行了一个 Web 服务比如 Flask 或 FastAPI 程序监听在0.0.0.0:8000VSCode 会自动检测到这个端口并在“端口”面板里显示出来还会自动做出本地转发你直接访问http://localhost:8000就行不需要手动开任何隧道。同理TensorBoard 默认端口 6006、Jupyter 默认 8888、Grafana 默认 3000都能这样直接转发。如果自动检测没生效也可以手动添加端口。点击“端口”面板的“添加端口”输入端口号。对于多端口范围可以使用类似8000-8010的方式添加VSCode 会逐一把它们映射到本地。端口转发背后用的是 SSH 隧道全部流量都走加密的 SSH 连接所以即使你的服务器是公网服务器也不用担心服务被外部直接扫描到端口。这是非常实用且安全的一个特性。5.2 远程开发时建议常开的几个命令连接服务器后所有在 VSCode 内置终端里执行的命令都是直接跑在服务器上的。我建议你养成几个习惯长时间跑的实验用tmux或screen包起来。VSCode 连接断开后终端进程可能会被终止但tmux里的进程会继续运行。代码tmux new -s train python train.py然后按CtrlB再按D退出会话下次进来执行tmux attach -t train就能接着看输出。查看服务器资源占用不要只靠感觉用htop或nvidia-smi。前者比top直观得多后者的 GPU 显存、利用率都是训练时最关心的事。如果你用 conda记得在连接后的终端里先执行conda activate 环境名再跑代码。VSCode 的 Python 解释器选择和你终端里激活的环境是两回事最好保持一致否则可能出现“编辑器的解释器和终端里跑的不一样”这种鬼畜问题。5.3 与 WSL 的组合用法如果你的本机是 Windows且同时使用了 WSLWindows Subsystem for LinuxRemote-SSH 和 WSL 是可以叠加的。你可以先通过 WSL 进入本机 Linux 环境再从这个 Linux 环境发起 SSH 连接服务器。做法是在 WSL 终端里执行code命令启动 VSCode它会以 WSL 模式打开在 WSL 中配置 SSH key然后通过 Remote-SSH 连接服务器此时本地侧的插件与 WSL 环境互通如果你的服务器需要走本机 WSL 里配置的特殊网络通道这种组合能解决一些比较复杂的网络场景。坦白说对于多数用户直接用 Windows 原生的 OpenSSH Remote-SSH 就够了WSL 叠加属于进阶玩法适合本机开发环境已经深度 WSL 化的那部分人。5.4 远程 C/C 与 Python 环境的常用配置Remote-SSH 连上后最常被问到的就是“为什么没有代码提示”和“为什么无法跳转到定义”。对于 Python前面已经说了装 Python Pylance 扩展然后选中远程解释器。对于 C/C装 C/C 扩展后VSCode 会问你是否配置 IntelliSense 模式建议选择linux-gcc-x64然后指定 Include 路径比如includePath: [ ${workspaceFolder}/**, /usr/include/**, /usr/local/include/** ]这样跳转和补全基本就能正常工作了。如果你还要在远程调试 C 程序需要安装 gdb 并在 launch.json 里正确配置program和cwd路径这部分内容和本地调试很像只是路径指到了远程目录本地 VSCode 会自动处理路径映射。5.5 一些“不那么常见但很管用”的设置最后分享几个我平时会改的设置它们对远程开发体验提升很明显remote.SSH.showLoginTerminal设为 true这样连接时能看到 SSH 登录过程的完整日志排查密码验证和密钥认证时非常有帮助。remote.SSH.useLocalServer官方推荐开启连接复用后新窗口连接同一台服务器会更快。files.eol如果服务器代码是 Linux 行尾LF建议在设置里把默认行尾改成\n避免在 Windows 上编辑完代码传上去后出现 CRLF 混乱。search.useIgnoreFiles服务器上的项目经常有海量依赖目录node_modules、.git、虚拟环境开启忽略文件后全局搜索速度会快很多。在 settings.json 里加入remote.SSH.defaultForwardedPorts: [{localPort: 8888, remotePort: 8888}]这类规则可以让常用端口每次连接后自动转发省得每次手点。写在最后的一点体会实话说从最早用 Xshell 敲命令到后来折腾 PyCharm 远程解释器再到现在主力使用 VSCode Remote-SSH我对远程开发这件事最大的感受是工具不是越复杂越好而是越“无感”越好。Remote-SSH 好就好在它不改变你写代码的方式你依然是一个编辑器、一个终端、一个文件树只是这些背后跑在另一台机器上。等你习惯了这种模式本地和远程的边界感会越来越模糊这反而是最舒服的状态。最后再分享一个小技巧如果你第一次连接某台服务器建议先不要急着开大项目先连上去随便打开一个空目录确认基础链路稳定了再加载大型工程。远程开发最忌“没走稳就想跑”把 SSH 本身的问题先排除干净后面一切都会顺畅很多。