INPSD 知识库

Appearance

VSCode Remote-SSH 连接常见问题解决 ​

在使用 VSCode 的 Remote-SSH 插件连接远程服务器时，经常会遇到一些连接失败或卡顿的问题。本文总结了常见的错误及其对应的解决方法。

1. 一直卡在 "Setting up SSH Host..." ​

现象： 在尝试连接远程服务器时，VSCode 状态栏一直显示 "Setting up SSH Host..." 或 "Downloading VS Code Server..."，最终可能提示超时。

原因： 通常是因为远程服务器处于无外网环境，或者连接外部网络的网络状态极差，导致无法顺利从 GitHub/微软服务器下载 VS Code Server。

解决方法（离线安装）：

第一个文件 vscode-server-linux-x64.tar.gz 解压解包后名为 vscode-server-linux-x64 文件夹改名为 server 放在 /home/${user}/.vscode-server/cli/servers/Stable-f1e16e1e6214d7c44d078b1f0607b2388f29d729/server/ 目录下. 第二个文件 vscode_cli_alpine_x64_cli.tar.gz 解压解包后名为 code 的文件改名为 code-${commit_id}放在/home/${user}/.vscode-server/目录下

x86:
https://vscode.download.prss.microsoft.com/dbazure/download/stable/c9d77990917f3102ada88be140d28b038d1dd7c7/vscode-server-linux-x64.tar.gz
https://vscode.download.prss.microsoft.com/dbazure/download/stable/f1e16e1e6214d7c44d078b1f0607b2388f29d729/vscode_cli_alpine_x64_cli.tar.gz 
arm:
https://vscode.download.prss.microsoft.com/dbazure/download/stable/${commit_id}/vscode-server-linux-arm64.tar.gz
https://vscode.download.prss.microsoft.com/dbazure/download/stable/${commit_id}/vscode_cli_alpine_arm64_cli.tar.gz
win 下载
https://vscode.download.prss.microsoft.com/dbazure/download/stable/${commit_id}/vscode-server-win32-x64.zip
https://vscode.download.prss.microsoft.com/dbazure/download/stable/${commit_id}/vscode_cli_win32_x64_cli.zip
  1. 获取 Commit ID：在 VSCode 菜单栏点击 帮助(Help) -> 关于(About)，复制 Commit 的哈希值（例如 e18005f0...）。
  2. 在本地电脑（有外网）下载对应的 server 压缩包：
    • 通用链接格式：https://update.code.visualstudio.com/commit:${Commit_ID}/${Target_Platform}/${Edition}
    • ${Commit_ID}：替换为你复制的哈希值。
    • ${Target_Platform}：根据远程服务器系统及 CPU 架构替换。这决定了您需要下载哪个（或哪些）文件：
      • 标准 Linux (Ubuntu, CentOS 等)
        • server-linux-x64：适用于绝大多数 64 位 Intel/AMD 处理器 (如 Core i7, AMD Ryzen)。
        • server-linux-arm64：适用于 64 位 ARM 处理器 (如树莓派 4+, AWS Graviton, Ampere Altra)。
        • server-linux-armhf：适用于 32 位 ARM 处理器 (如树莓派 3)。
      • Alpine Linux
        • server-alpine-x64：适用于 64 位 Intel/AMD 处理器。
        • server-alpine-arm64：适用于 64 位 ARM 处理器。

        • 注意：对于 Alpine Linux，除了 vscode-server-alpine-...，通常还需要下载一个名为 vscode-cli-alpine-${ARCH}-cli.tar.gz 的附加包，并将其内容解压到 ~/.vscode-server/bin/${Commit_ID}/ 目录中。

      • macOS
        • server-darwin：适用于 Intel 芯片的 Mac。
        • server-darwin-arm64：适用于 Apple Silicon (M1/M2) 芯片的 Mac。
      • Windows
        • server-win32-x64：适用于 64 位 Windows。
        • server-win32-arm64：适用于 ARM 架构的 Windows。
    • ${Edition}：你的 VSCode 客户端版本，正式版为 stable，预览版（Insiders）为 insider。
    • 示例（Linux x64 稳定版）：https://update.code.visualstudio.com/commit:${Commit_ID}/server-linux-x64/stable
  3. 上传并解压：
    • 将下载的压缩包上传到远程服务器对应的 ~/.vscode-server/bin/${Commit_ID} 目录下（如果目录不存在则创建）。
    • 针对 Linux / macOS 服务器 (通常下载为 .tar.gz 文件)：
      bash
      # 例如：vscode-server-linux-x64.tar.gz
tar -zxf vscode-server-YOUR-PLATFORM.tar.gz --strip-components 1
    • 针对 Windows 服务器 (通常下载为 .zip 文件，需要 PowerShell 或其他解压工具)：
      powershell
      # 例如，在 PowerShell 中：
Expand-Archive -Path vscode-server-win32-YOUR-PLATFORM.zip -DestinationPath .
      或在 Git Bash/WSL 中使用 unzip 或 tar。
    • 创建一个完成标记文件：touch 0
  4. 重新使用 VSCode 连接即可。

2. 提示 "Permission denied (publickey)" ​

现象： 连接时终端输出 "Permission denied (publickey)" 或类似身份验证失败的错误。

原因： SSH 密钥未正确配置，或者服务端拒绝了密码登录且未提供有效的私钥。

解决方法：

  1. 确认你是否在 .ssh/config 中配置了正确的私钥路径：
    ssh-config
    Host my-server
    HostName 192.168.1.100
    User root
    IdentityFile ~/.ssh/id_rsa
  2. 确保公钥已经追加到了远程服务器的 ~/.ssh/authorized_keys 文件中。
  3. 检查远程服务器的 ~/.ssh 目录及 authorized_keys 文件的权限（目录通常应为 700，文件应为 600）。

3. "Could not establish connection... (The VS Code Server failed to start)" ​

现象： 报错提示无法建立连接，VS Code Server 启动失败。或者经常自动断开连接。

原因： 可能是远程服务器上的 VS Code Server 文件损坏，或者 Node.js 进程卡死、内存耗尽。

解决方法： 清理远端的 VS Code Server 并重试：

  1. 使用普通的终端（如 PuTTY, Xshell, 或本机的终端）SSH 登录到远程服务器。
  2. 删除 .vscode-server 目录：
    bash
    rm -rf ~/.vscode-server
    (注：如果有其他正在运行的 vscode 进程，可以使用 killall node 强制结束相关的残余进程)
  3. 再次在本地通过 VSCode 发起连接，让其重新下载并安装 Server 即可。

4. SSH 频繁断开或连接超时（Timeout） ​

现象： 连接建立后，稍微闲置一段时间连接就会断开，或者一开始连接就报 Timeout。

原因： 防火墙限制了长连接，或者 SSH 客户端与服务端的保活（KeepAlive）机制没有开启。

解决方法： 在本地电脑的 SSH 配置文件（通常是 ~/.ssh/config）中，为该 Host 添加心跳保活配置：

ssh-config
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

这表示每 60 秒向服务器发送一个保活包，如果连续 3 次无响应才断开连接。