很多用VSCode连服务器开发的同学应该都见过右下角那个转圈圈的提示Setting up SSH Host或者Downloading VS Code Server紧接着就是无休止的Retrying...重复尝试。这个状态卡住几秒还算正常如果卡上十分钟、反复重试几十次那基本可以断定是远程连接链路里的某个环节出了毛病。这篇文章就把我这些年排查类似问题踩过的坑、总结出的方法完整写一遍从原理到实操争取让你看完之后能自己定位并解决不用再靠一遍遍重启VSCode碰运气。1. 先搞清楚远程连接时VSCode到底在干什么1.1 远程连接的基本流程VSCode通过Remote-SSH插件连接服务器本质上分三步本地通过SSH协议登录到远程服务器。在远程服务器上安装一个名为vscode-server的服务端组件如果还没装的话。本地客户端与服务端建立通信通道把界面、终端、插件都搬到本地窗口里。你看到的反复重试绝大多数发生在第二步——服务端组件的下载、解压、安装环节。换句话说SSH本身很可能连通了但服务端安装没能顺利完成于是客户端只能一遍遍重试直到成功或者你放弃。1.2 反复重试真正卡住的节点我用一个实际现象来说明当你连接远程主机时左下角状态栏会显示Setting up SSH Host或类似的字样然后过几秒开始显示Retrying...。如果此时打开VSCode的输出面板快捷键CtrlShiftU然后选Remote - SSH你会看到类似这些日志[15:32:01.123] Remote server is still downloading... [15:32:11.456] Remote server is still downloading... [15:32:21.789] Remote server is still downloading...或者[15:32:05.234] Failed to download the server. Error: ... [15:32:15.567] Retrying...日志里出现still downloading说明本地在等远程服务器下载完毕出现Failed to download说明远程下载失败、正在重试。这两种情况对应的原因和排查方式完全不同所以第一步永远是看日志而不是盲猜。注意看日志是排查一切远程连接问题的第一步。VSCode输出面板里的信息比右下角的弹窗准确得多也详细得多。2. 六种常见原因按出现概率排序排查这类问题与其东一榔头西一棒子不如按出现频率从高到低逐个排除。我按自己的实际经验列出了六种最常踩中的原因覆盖面可以到九成以上。2.1 网络波动导致的下载中断这种情况最常见尤其当服务器在国内、或者你的本地网络到服务器之间的链路不稳定时。vscode-server的体积在几十到一百多MB之间如果网络质量差下载过程容易中途断掉而VSCode的重试机制并不算智能——它不会断点续传每次都是从头重新下载。典型症状日志里反复出现Downloading VS Code Server或still downloading字样偶尔有Connection timed out之类的网络错误。最终结果就是无限重试。解决方案手动下载并上传到服务器绕过本地的网络下载环节。这是最可靠的办法后面我会详细写步骤。2.2 服务器无法访问GitHub下载地址vscode-server的安装包托管在GitHub Release上服务器如果无法访问GitHub比如服务器在国内、安全组没放开外网、或者公司网络有代理限制下载就永远无法成功。典型症状日志里明确看到Failed to download the server或者Cannot connect to host重试很多次也一直失败。解决方案方法很多给服务器配置代理、使用国内镜像源、或者手动下载后scp上传。具体操作后面展开。2.3 known_hosts与密钥认证问题这个容易被忽略。VSCode虽然每次弹出的提示可能在重试其实真正的阻塞点是SSH握手。如果本地known_hosts文件里记录了旧的主机指纹而服务器的密钥变了重装系统、重建容器、换了密钥对都会导致SSH握手会被拒绝而VSCode的重试机制会不断尝试表现就是反复重试。典型症状日志里出现Host key verification failed。解决方案删掉known_hosts里对应的那行记录重新连接。具体命令ssh-keygen -R 你的服务器IP或者手动编辑~/.ssh/known_hosts文件删掉对应IP所在行。如果connect之后还需要交互输入密码而VSCode的密码提示一直没弹出来那同样会表现为卡住或重试这种情况建议配置SSH密钥登录。提示用ssh -v命令手动测试连接是最快的验证方式。如果手动SSH能正常进入问题大概率在别处如果手动SSH都失败那问题就在SSH层不用怀疑VSCode。2.4 vscode-server目录损坏导致安装异常服务器上的~/.vscode-server目录是VSCode服务端组件的存放位置。如果这个目录里的文件不完整比如上次下载到一半强制断开、权限不对比如之前用root装的现在换普通用户连、或者版本混乱本地VSCode升级后版本不匹配就会导致服务端反复尝试重新安装。典型症状日志里出现Failed to install server或者Empty response from server重试多次后偶尔能连上、偶尔连不上非常随机。解决方案直接删掉服务器上的~/.vscode-server目录让VSCode重新装一套干净的服务端。命令rm -rf ~/.vscode-server然后重新连接。这相当于给远程服务端做了一次重装系统能解决大部分安装层面的问题。2.5 远程服务器磁盘空间不足这个原因比较隐蔽。vscode-server本身不大但如果你的服务器磁盘已经用了90%以上下载安装过程中临时文件可能写不进去或者解压不完整同样会触发失败重试。典型症状日志里出现ENOSPC: no space left on device或者类似错误。解决方案清理服务器磁盘空间可用命令df -h看看挂载点的使用率清理掉不需要的日志文件、Docker镜像、缓存等。磁盘使用率降到合理水平后重新连接即可。2.6 SSH配置与代理设置互相干扰如果你本地或服务器配置了代理比如~/.ssh/config里指定了ProxyCommand而代理本身不稳定或不可用SSH连接就会建立失败同样会表现为反复重试。典型症状日志里出现Connection closed或者ProxyCommand failed等字段。解决方案检查~/.ssh/config里是否配置了ProxyCommand、HostName等字段临时注释掉再测试连接。也可以对比一下取消代理直接连接是否正常。3. 实操目录清理与手动上传方案的完整记录3.1 快速重置vscode-server目录如果你确认网络和SSH都没问题那最值得尝试的操作就是重置远程服务端目录。这个操作我在很多台机器上用下来成功率极高。完整操作步骤在本地终端手动连接服务器ssh 用户名服务器IP删除旧的vscode-server目录rm -rf ~/.vscode-server退出SSH连接回到本地VSCode按F1并执行Remote-SSH: Connect to Host重新连接。耐心等待正常情况下VSCode会自动重新下载并安装服务端这一次通常会成功。如果这样仍然失败那再尝试手动安装方案——这个方法虽然步骤多一点但稳得一批。3.2 手动下载安装vscode-server的完整步骤先获取commit id在本地找到VSCode安装目录里package.json查看commit字段的值或者在连接失败时的VSCode日志里直接找到commit id日志里通常会显示类似[info] Resolving remote platform...之类的上下文。找到后记录下来。然后在本地下载对应版本的vscode-server压缩包。不同的服务器系统对应不同的文件名Linux x64系统vscode-server-linux-x64.tar.gzLinux arm64系统vscode-server-linux-arm64.tar.gzLinux 32位系统vscode-server-linux-arm32.tar.gz下载地址格式是https://update.code.visualstudio.com/commit:你的commitId/server-linux-x64/stable下载完成后把压缩包上传到服务器并在目标目录解压scp vscode-server-linux-x64.tar.gz 用户名服务器IP:/tmp/ ssh 用户名服务器IP cd /tmp mkdir -p ~/.vscode-server/bin/你的commitId tar -xzf vscode-server-linux-x64.tar.gz -C ~/.vscode-server/bin/你的commitId --strip-components1关键一步解压后的目录结构要调整正确。压缩包解压出来是一个vscode-server-linux-x64文件夹但VSCode期望服务端直接在~/.vscode-server/bin/commitId/下面所以要加--strip-components1参数让它直接解压到目标目录里否则识别不到。注意commitId的路径必须与本地VSCode版本完全一致。如果本地VSCode之后升级了commitId变了服务器上就会再触发一次下载这是正常现象不是出bug了。手动上传完成后重新在VSCode里连接这一次连接速度会非常快因为服务器端已经有现成的服务端组件不需要重新下载。3.3 用国内镜像或代理下载服务端如果纯粹是GitHub下载慢导致的重试我实测比较有效的是配置服务器代理或者在服务器上用国内镜像下载。以国内环境为例很多公共镜像站也提供了vscode-server的下载镜像可以把下载地址里的域名替换成镜像域名。在服务器上直接执行export http_proxyhttp://你的代理地址:端口 export https_proxyhttp://你的代理地址:端口注意这个代理环境和前面提到的安全审查无关只是在讨论网络连接的常规配置。如果公司或实验室有内部代理规则遵循即可。但归根到底最稳的还是手动下载上传因为不依赖服务器和本地之间的实时下载链路也不依赖GitHub的可用性。4. 完整排查流程一条命令一条命令定位问题每次遇到反复重试我都按下面这个顺序排查基本不浪费多余的时间。4.1 第一步手动SSH测试先绕开VSCode在终端里直接测试SSH连接ssh 用户名服务器IP如果这一步能顺利进入服务器SSH链路没问题继续往下确认服务端状态。如果这一步也卡住或报错那么问题在SSH层和VSCode无关建议检查服务器防火墙是否放行22端口密钥文件权限~/.ssh/id_rsa应为600known_hosts是否有冲突记录4.2 第二步查看VSCode日志定位具体报错打开VSCode输出面板切换下拉框选择Remote - SSH看具体的连接日志。如果大量出现still downloading说明SSH已通服务端下载中重点排查网络问题。如果出现Failed to download说明远程服务器下载受限考虑手动上传方案。如果出现Host key verification failed删known_hosts后再连。如果出现ENOSPC清理服务器磁盘。记住一个排查原则日志里每一行错误都对应一类问题不要被Retrying字样迷惑要顺着日志往上找真正出错的那一行。4.3 第三步检查服务器端目录与进程SSH连上服务器后执行ls -la ~/.vscode-server/bin/可以看到已安装的服务端目录列表。另外用ps aux | grep vscode-server查看是否有残留进程。如果残留了僵死进程用kill -9清理掉再重连。有时候旧的残留进程会占用端口或锁文件新的服务端起不来表现也是反复重试。这种情况删掉整个目录重启服务端就能解决。5. 常见问题速查表为了方便急用的朋友我把典型场景、报错信息和对应解法整理成一张表典型现象报错关键词最直接的解法一直显示Setting up SSH Host然后重试still downloading手动下载上传vscode-server服务器下载不成功一直失败Failed to download the server给服务器配代理或手动上传安装包SSH提示主机密钥不匹配Host key verification failedssh-keygen -R清除旧记录后重连连接时偶尔成功偶尔失败Empty response from server删除~/.vscode-server目录后重连日志里报磁盘空间错误ENOSPC: no space left on device清理服务器磁盘保留15%以上空间配置过代理后连不上ProxyCommand failed检查或临时注释~/.ssh/config里的代理配置6. 一点长期建议让远程连接更稳定排查完问题之后再分享几个我长期实测有效的实践能减少这类问题再次出现的概率。第一优先使用SSH密钥而不是密码登录。密码登录会在连接建立过程中多一层交互一旦卡在密码提示环节VSCode会频繁重试。换成密钥登录后认证过程自动完成整个过程少了人为交互稳定性高一个数量级。第二本地VSCode升级要谨慎。本地版本跳得越快vscode-server版本不匹配的概率越大触发重新下载的可能也越高。固定使用一个稳定版本或者做好每次升级后可能需要重置服务端目录的心理准备。第三服务器的~/.vscode-server目录不要手动乱改。有的人会进去删删改改反而把服务端弄坏。如果不需要特殊定制就让VSCode自己管理这个目录。真出问题了就整个删除重置别做零碎的修改。第四配置好ServerAliveInterval。在~/.ssh/config里为常用主机加上Host my_server HostName 你的服务器IP User 你的用户名 ServerAliveInterval 60这个配置会每60秒发一次保活心跳防止长时间没有操作后连接被服务端静默断开。远程开发时挂着terminal写代码这个配置能减少突然就断开重连的体验问题。我把整个排查经验总结成一句话反复重试四个字背后有至少六个可能的原因先看日志再分叉排查实在不行就手动装服务端。这套方法帮我处理过不少次远程连接问题现在也写在这里希望对你有用。