VS Code Remote SSH 远端平台识别的固定配置方法

VS Code Remote - SSH 连接一台新主机时，会根据远端环境判断应该使用哪个 VS Code Server 平台。如果自动识别不稳定，最直接的处理是给 SSH 主机别名固定 remote.SSH.remotePlatform：Linux 写 linux，Windows 写 windows，macOS 写 mac。这个设置只解决“远端平台映射”问题，不负责修复密钥、端口转发或终端环境变量。

官方地址：https://code.visualstudio.com/docs/remote/ssh

先确认 Remote - SSH 使用的主机别名

打开左侧活动栏的 Remote Explorer，在下拉框中选择 SSH Targets，找到目标条目。这里要记下的是列表中的 Host 别名，不是远端 IP，也不是远端显示名称。比如 SSH 配置里的 Host build-host，映射键就应当是 build-host。

选择目标条目并连接。如果 VS Code 显示 Select the platform of the remote host，按照远端实际系统选择 Linux、Windows 或 macOS。这次选择会成为后续连接判断的依据；图中的界面是原创操作示意图，不是软件截图。

在 settings.json 固定远端平台映射

如果每次都弹出平台选择，或自动判断成了错误系统，可以打开命令面板，执行 Preferences: Open User Settings (JSON)。在顶层对象中加入下面的配置。JSON 不支持注释，因此字段含义放在代码块外解释。

{
  "remote.SSH.remotePlatform": {
    "build-host": "linux",
    "test-win": "windows",
    "mac-mini": "mac"
  }
}

只保留实际存在的 Host 别名即可。若只连接 Linux 主机，最小配置可以只写 build-host。保存后观察设置编辑器是否仍有红色 JSON 错误标记；没有语法错误，且值与远端系统相符，才进入下一步。

清理错误映射并检查连接结果

1. 删除错误键：在 remote.SSH.remotePlatform 对象中删除对应 Host 行；如果对象已经没有成员，也可以删除整个设置项。
2. 重新连接：回到 Remote Explorer 的 SSH Targets，重新选择同一 Host。再次出现平台选择时，按远端真实系统选择。
3. 检查状态：远程窗口打开后，看左下角 Remote 状态是否显示目标 Host，并在 Remote - SSH 输出中确认服务启动过程没有平台不匹配提示。

如果普通 SSH 能登录但 Remote - SSH 仍失败，不要把所有问题都归因于平台映射。平台设置只决定 VS Code Server 的目标系统；密钥、代理跳板、远端磁盘权限和网络下载能力需要分别排查。

常见问题

键名应该写 IP 地址还是 SSH 别名？

优先写 SSH 配置中的 Host 别名，也就是 Remote Explorer 实际使用的条目名。只有当连接配置本身把 IP 当作 Host 名时，才使用 IP 作为键。

远端是 Alpine Linux，值仍然写 linux 吗？

是。这里的值表示 VS Code Remote - SSH 的目标平台，不是 Linux 发行版名称；Alpine 的兼容性和依赖问题需要另外按照官方远程开发要求处理。

改完设置后还在读取旧平台怎么办？

先确认修改的是当前用户或当前 Profile 使用的 settings.json，再删除错误 Host 映射并重新连接。不要同时在多个设置层级保留同名键，以免排查时混淆。