VS Code Remote-SSH 一直卡在"正在下载 VS Code 服务器"？一次真实排障记录与详细解决方法
适用场景 ：Windows 本地电脑使用 VS Code 的 Remote - SSH 扩展连接远程 Linux 服务器（例如实验室 GPU 服务器），连接过程中长时间提示"正在下载 VS Code 服务器"。
本文环境 ：Windows + VS Code + Remote - SSH + Linux 远程服务器。示例服务器地址为
128.60.233.5（仅作案例展示）。处理结果：本次连接最终已恢复正常。需要说明的是，没有保留完整的 Remote - SSH 错误日志，因此下文对具体根因的判断属于排障推测，而不是已经证实的唯一原因。
文章目录
- [VS Code Remote-SSH 一直卡在"正在下载 VS Code 服务器"？一次真实排障记录与详细解决方法](#VS Code Remote-SSH 一直卡在“正在下载 VS Code 服务器”？一次真实排障记录与详细解决方法)
-
- [一、问题现象：SSH 远程连接一直卡在下载服务器](#一、问题现象：SSH 远程连接一直卡在下载服务器)
- [二、优先解决：让本地电脑下载 VS Code Server](#二、优先解决：让本地电脑下载 VS Code Server)
-
- [1. 打开 VS Code 用户设置（JSON）](#1. 打开 VS Code 用户设置（JSON）)
- [2. 在 `settings.json` 中添加配置](#2. 在
settings.json中添加配置) - [3. 重新连接远程主机并输入密码](#3. 重新连接远程主机并输入密码)
- [4. 等待 VS Code Server 下载、传输和安装](#4. 等待 VS Code Server 下载、传输和安装)
- 三、如果仍然卡住，按下面顺序继续排查
-
- [方法一：在 Windows PowerShell 中独立测试 SSH](#方法一：在 Windows PowerShell 中独立测试 SSH)
- [方法二：用 VS Code 自带命令清理服务端组件](#方法二：用 VS Code 自带命令清理服务端组件)
- [方法三：查看 Remote - SSH 的详细日志](#方法三：查看 Remote - SSH 的详细日志)
- [方法四：确认本机能否访问 VS Code 下载服务](#方法四：确认本机能否访问 VS Code 下载服务)
- 四、为什么这一方法通常有效？
- 五、最终总结：建议按这个优先级排查
- 参考资料
一、问题现象：SSH 远程连接一直卡在下载服务器
使用 VS Code 连接远程服务器时，右下角持续显示：
"设置 SSH 主机 128.60.233.5：正在下载 VS Code 服务器"
如下图所示：
此时 VS Code 无法正常打开远程工作区，看起来像"SSH 连不上"，但这个提示本身并不能证明 SSH 网络连接失败。连接流程大致为：
text
Windows 本地 VS Code
│
▼
通过 SSH 连接远程 Linux 主机
│
▼
身份验证（密码或 SSH 密钥）
│
▼
检查 / 安装 / 启动 VS Code Server
│
▼
建立 VS Code 与远程服务器的通信
│
▼
打开远程文件、终端和开发环境VS Code Server 是 Remote - SSH 在远程主机上运行的配套组件，负责支持远程编辑、扩展和终端等能力。首次连接、VS Code 更新或服务端组件损坏时，都可能涉及下载或重新安装。
可能出现问题的原因
- 远程服务器网络受限：实验室或校园网 Linux 主机无法顺利访问 VS Code Server 下载站点。
- 服务器组件下载或安装异常：网络不稳定、空间不足、权限问题，或已有安装残留。
- 身份验证提示被忽略：VS Code 正在等待输入密码，但弹出的 SSH 终端不明显。
- SSH 连接本身异常：主机不可达、科学上网，SSH 端口被阻断或账号不正确。
本次案例中，结合"下载 VS Code 服务器"的提示，优先尝试修改 VS Code Server 下载方式，并显示 SSH 登录终端。
二、优先解决：让本地电脑下载 VS Code Server
这是本文最值得优先尝试的方法。
1. 打开 VS Code 用户设置（JSON）
先取消或关闭一直等待的 Remote-SSH 连接窗口，返回 VS Code 的本地窗口。
按下快捷键：
text
Ctrl + Shift + P打开命令面板后，在搜索框中输入：
text
Preferences: Open User Settings (JSON)如果 VS Code 使用中文界面，也可以搜索：
text
首选项: 打开用户设置(JSON)选择相应命令并回车，如下图：
这里要注意：打开的是 User Settings（用户设置） ，而不是某个项目的 .vscode/settings.json。前者可以对当前 Windows 用户下的 Remote-SSH 连接行为生效。
2. 在 settings.json 中添加配置
如果文件原来为空或只有一对花括号，可以直接写入：
json
{
"remote.SSH.localServerDownload": "always",
"remote.SSH.showLoginTerminal": true,
"remote.SSH.useLocalServer": false
}如果 settings.json 中已经有其他配置，不要直接覆盖整个文件，应将这三个键合并到原有的 JSON 对象中，并注意相邻配置项之间的英文逗号。例如：
json
{
"editor.fontSize": 15,
"files.autoSave": "afterDelay",
"remote.SSH.localServerDownload": "always",
"remote.SSH.showLoginTerminal": true,
"remote.SSH.useLocalServer": false
}这三个选项分别表示：
| 配置项 | 含义 | 在排障中的作用 |
|---|---|---|
remote.SSH.localServerDownload: "always" |
强制优先在本地电脑下载 VS Code Server，并通过 SSH 传到远程主机 | 规避远程服务器无法访问下载地址的问题 |
remote.SSH.showLoginTerminal: true |
显示 SSH 登录时使用的终端 | 及时看到并处理密码、密钥口令等提示 |
remote.SSH.useLocalServer: false |
禁用 Remote-SSH 的本地辅助服务器模式 | 这是官方建议的连接卡顿排障配置之一；并非所有电脑都必须设置 |
其中，第一项是针对"远程下载卡住"最关键的尝试。需要注意，改成本地下载后，Windows 电脑仍然需要能够访问 VS Code 的下载服务，并且 SSH 传输正常。
按 Ctrl + S 保存设置。
3. 重新连接远程主机并输入密码
重新执行：
text
Ctrl + Shift + P
→ Remote-SSH: Connect to Host...
→ 选择远程主机 128.60.233.5（或自己配置的 SSH 主机别名）如果使用账号密码登录，此时可能看到类似如下终端提示：
截图里同时出现了：
- "此 shell 正在本地计算机上运行，而不是在连接的远程计算机上运行" ：说明这里显示的是 VS Code 本机上的 SSH 登录/安装终端，不意味着最终远程工作区已经打开，更不能单凭这行字认定连接失败。
128.60.233.5's password:：表示 SSH 在请求账户密码。输入你用于登录远程 Linux 服务器的密码并按回车。
注意：Linux/SSH 密码输入一般不会显示字符、星号或光标移动，这是正常的。
4. 等待 VS Code Server 下载、传输和安装
完成身份验证后，VS Code 可能仍短暂显示：
"设置 SSH 主机......正在下载 VS Code 服务器"
但是很快就下载完成了。
三、如果仍然卡住，按下面顺序继续排查
方法一：在 Windows PowerShell 中独立测试 SSH
打开 Windows PowerShell（不是必须通过 VS Code），执行：
powershell
ssh 用户名@128.60.233.5请把 用户名 换成你在服务器上的真实 Linux 登录用户名。如果服务器使用自定义端口（例如 2222），可以使用：
powershell
ssh -p 2222 用户名@128.60.233.5如果你已经在 ~/.ssh/config 中配置了主机别名，也可直接执行 ssh 主机别名，确保与 VS Code 使用相同的端口和跳板机配置。
根据结果判断：
| 命令行结果 | 初步判断 | 下一步 |
|---|---|---|
| 能输入密码并进入 Linux 命令行 | 基础 SSH 连接可用 | 优先排查 VS Code Server 下载、安装或启动 |
Connection timed out |
主机网络、科学上网、端口等可能有问题 | 检查内网可达性、校园网/科学上网 与服务器状态 |
Connection refused |
主机可达但目标端口拒绝连接，或服务未监听 | 检查 SSH 端口与服务器 sshd 服务 |
Permission denied |
身份验证失败 | 核对用户名、密码、密钥和服务器授权配置 |
Could not resolve hostname |
主机名或 SSH 别名解析失败 | 核对主机地址和 SSH 配置文件 |
特别提醒 ：10.x.x.x 一般属于私有 IP 地址。对于实验室服务器，离开校园网后可能必须先连接指定 科学上网 或跳板机，不能默认从互联网直接访问。
方法二：用 VS Code 自带命令清理服务端组件
如果 PowerShell 中 SSH 正常，但 VS Code 仍无法连接，尝试：
text
Ctrl + Shift + P
→ Remote-SSH: Kill VS Code Server on Host...
→ 选择出问题的远程主机
→ 再次连接这是 VS Code 官方给出的排障命令之一，适合处理服务端组件安装不完整、进程卡死等情况。
注意：此命令会停止并清理对应的 VS Code Server 安装，可能导致远程 VS Code 扩展需要重新准备；通常不涉及项目代码、训练数据或 Conda 环境，但在多人共用服务器上应只操作自己的登录账户，避免擅自修改他人的文件或服务。
不要在不理解作用范围的情况下直接执行网上看到的 rm -rf 命令。
方法三：查看 Remote - SSH 的详细日志
在 VS Code 中按 Ctrl + Shift + P，输入：
text
Remote-SSH: Show Log也可以使用：
text
查看（View）→ 输出（Output）→ 下拉选择 Remote - SSH重点查看日志中最后出现的 ERROR、Failed、Permission denied、timeout 或安装命令相关信息。可能遇到的情况包括：
| 典型错误提示 | 常见排查方向 |
|---|---|
Failed to download |
本地/远程下载站点网络访问失败、代理设置或防火墙 |
No space left on device |
远程用户目录或临时目录空间不足 |
Permission denied |
SSH 账号认证或远程安装目录写入权限 |
The VS Code Server failed to start |
服务端启动异常；尝试清理服务端组件后重新安装 |
open failed: administratively prohibited |
SSH 端口转发可能受远程服务器策略限制，需管理员检查 |
可以在成功 SSH 登录后，执行以下只读检查，查看可用空间和用户目录权限：
bash
df -h ~
ls -ld ~ ~/.vscode-server 2>/dev/null如果涉及公司、学校共享主机的代理、端口转发或 SSH 服务配置，请让管理员协助，不建议自行修改系统级 SSH 配置。
方法四：确认本机能否访问 VS Code 下载服务
即使设置了 "remote.SSH.localServerDownload": "always"，本机也必须能访问必要的 HTTPS 下载站点。根据 VS Code 官方文档，安装 VS Code Server 时涉及以下地址：
text
https://update.code.visualstudio.com/
https://vscode.download.prss.microsoft.com/如果 Windows 电脑自身网络受限，本地下载也可能失败。遇到这种情况，应检查本机网络代理、校园网/公司网络策略以及 Remote - SSH 日志，而不是反复输入服务器密码。
四、为什么这一方法通常有效？
核心是改变 VS Code Server 组件的获取路径。
默认逻辑（VS Code Remote - SSH 通常先尝试远程下载，失败后可以回退到本地下载）：
text
远程 Linux 服务器 ────[下载]────> VS Code Server 安装包
│
└─ 如果服务器访问外网受限，可能出现下载失败或连接卡住修改后的逻辑 （remote.SSH.localServerDownload = "always"）：
text
Windows 本地电脑
│
├─ 通过本机网络下载 VS Code Server
│
└─ 通过 SSH 将安装文件传给远程 Linux 主机
│
└─ 安装并启动 VS Code Server因此，如果远程 GPU 服务器只能访问内网，而 Windows 电脑可以访问外网并连到该服务器，"本地下载 + SSH 传输"通常比依赖远端下载更可靠。
不过，这个设置无法解决所有 Remote-SSH 错误。例如，SSH 认证失败、远程磁盘满、服务端操作系统不兼容、端口转发被禁用等问题，仍需要根据日志分别处理。
五、最终总结：建议按这个优先级排查
- 先打开本地用户设置 JSON ，添加
remote.SSH.localServerDownload: "always"。 - 开启
remote.SSH.showLoginTerminal: true，避免遗漏密码提示；必要时设置remote.SSH.useLocalServer: false。 - 重新连接主机，看到密码提示后正常输入；下载提示出现后观察日志进展。
- 如果仍然失败，使用 Windows PowerShell 独立执行
ssh 用户名@服务器地址，区分 SSH 网络问题和 VS Code Server 问题。 - SSH 正常但 VS Code 异常时，尝试
Remote-SSH: Kill VS Code Server on Host...，或根据日志进一步检查磁盘、权限和网络。