INPSD 知识库

Appearance

VSCode Remote-SSH 插件设置项 (Settings) 详解 ​

在使用 Remote-SSH 插件时，除了配置系统的 ~/.ssh/config 文件，VSCode 自身也提供了一系列插件设置项（在 VSCode 的 settings.json 中以 remote.SSH. 开头）。

合理配置这些选项可以解决很多网络连接超时、权限不足或安装环境的边缘问题。

1. 核心路径配置 ​

remote.SSH.configFile ​

  • 说明：指定 VSCode 使用的自定义 SSH 配置文件路径。
  • 适用场景：默认情况下 VSCode 会读取操作系统的默认配置（如 ~/.ssh/config）。如果你有多个配置文件，或者不想污染全局配置，可以单独指定一个绝对路径。
  • 示例："remote.SSH.configFile": "D:\\my_ssh_configs\\vscode_config"

remote.SSH.path ​

  • 说明：指定本地 SSH 客户端可执行文件（ssh.exe 或 ssh）的绝对路径。
  • 适用场景：系统环境变量 PATH 中没有 ssh 命令，或者你想使用特定版本的 SSH 客户端（如 Git Bash 自带的 ssh、PuTTY 等）时使用。
  • 示例："remote.SSH.path": "C:\\Program Files\\Git\\usr\\bin\\ssh.exe"

2. 服务端安装与下载配置（重点） ​

remote.SSH.serverInstallPath ​

  • 说明：自定义远端服务器上 VS Code Server 的安装目录。
  • 适用场景：默认情况下，VS Code 会将服务端程序和缓存安装在远程机器的 ~/.vscode-server 目录下。如果你的用户主目录（Home 目录）磁盘空间不足，或者由于权限、磁盘配额限制无法写入，可以通过此项更改安装位置。
  • 示例配置（按服务器别名进行单独配置）：
    json
    "remote.SSH.serverInstallPath": {
    "my-dev-server": "/data/workdir/my_user/.vscode-server",
    "another-server": "/tmp/.vscode-server"
}

remote.SSH.localServerDownload ​

  • 说明：控制从哪里下载 VS Code Server。可选值：auto、always、off。
  • 适用场景：
    • auto（默认）：如果探测到远程服务器无法联网，VSCode 会尝试先在本地电脑下载，然后通过 SCP 自动传给远程服务器。
    • always：强制始终在本地下载然后上传（适合远程机器完全没有外网的环境，能大幅减少卡在 "Downloading VS Code Server..." 的情况）。
    • off：仅让远程服务器自行下载（适合远程网络极好，而本地电脑网络较差的情况）。

3. 连接与交互排错配置 ​

remote.SSH.connectTimeout ​

  • 说明：连接远程主机的超时时间（单位：秒），默认 15 秒。
  • 适用场景：如果你的服务器网络延迟较高，或者需要复杂的堡垒机跳转、执行多步验证导致连接时间较长，很容易报 Timeout 错误。此时可以将该值调大（如 30 或 60）。

remote.SSH.showLoginTerminal ​

  • 说明：是否在连接时强制在底部面板显示 SSH 登录的终端窗口。
  • 适用场景：遇到连接卡死或报错时开启此项，可以直接看到 SSH 客户端底层的输出日志，非常有助于排查是否卡在密码输入、2FA 双因素验证或密钥报错上。

remote.SSH.useLocalServer ​

  • 说明：是否使用本地服务器来辅助管理 SSH 连接。
  • 适用场景：这是 VSCode 的一种底层连接机制。如果在默认状态下遇到连接极度不稳定、文件同步异常或各种奇怪的断开问题，可以尝试切换此选项（开/关）来改变底层通讯机制。

4. 系统探测配置 ​

remote.SSH.remotePlatform ​

  • 说明：手动指定远程主机的操作系统类型（linux、windows 或 macOS）。
  • 适用场景：通常 VSCode 会在连接初期自动执行脚本来探测远程系统的类型。但如果远程服务器使用了受限的 Shell 或特殊的配置，探测可能会失败或卡住。此时通过配置写死目标服务器的系统类型，可以加快连接速度并避免出错。
  • 示例配置：
    json
    "remote.SSH.remotePlatform": {
    "ubuntu-web": "linux",
    "win-jumpbox": "windows",
    "mac-builder": "macOS"
}