VSCode 远程 SSH 连接超时怎么配置 Config 文件

遇到 VSCode 远程 SSH 连接超时，最直接的方案是在本地 SSH 配置文件中添加心跳保活参数，或者调整 VSCode 插件的连接超时设置。

先说结论：修改本地 SSH Config 文件添加保活配置是通用且副作用最小的方法，适用于大多数网络波动导致的断开场景。

适合：远程服务器空闲自动断开或握手阶段超时
先准备：确认本地 ~/.ssh/config 文件可写
验收：重新连接后保持空闲不中断

命令速用版

grep -q "ServerAliveInterval" ~/.ssh/config || echo -e "Host *\n  ServerAliveInterval 60\n  ServerAliveCountMax 3" >> ~/.ssh/config
chmod 600 ~/.ssh/config

注：上述命令已做幂等处理，重复执行不会追加重复配置。若 ~/.ssh/config 文件不存在，请先创建。

为什么会这样

SSH 协议本身没有强制的心跳机制，中间网络设备（如防火墙、路由器）通常会清理长时间没有数据流动的 TCP 连接。VSCode 远程开发依赖 SSH 隧道，一旦底层连接被网络设备切断，插件就会报超时错误。通过配置 SSH 客户端定期发送空包（KeepAlive），可以告诉中间设备“连接仍在使用”，从而防止被误杀。

分步处理

步骤 1：检查配置文件路径
本地机器（运行 VSCode 的电脑）上，配置文件通常位于 ~/.ssh/config。如果文件不存在，可以新建一个。

步骤 2：编辑配置内容
使用文本编辑器打开该文件，添加以下内容。建议针对特定主机配置，避免影响其他 SSH 连接：

Host your_remote_host
  HostName 192.168.1.100
  User your_username
  ServerAliveInterval 60
  ServerAliveCountMax 3
  ConnectTimeout 30

其中 ServerAliveInterval 60 表示每 60 秒发送一次心跳，ConnectTimeout 30 表示连接建立阶段最多等待 30 秒。

步骤 3：调整 VSCode 插件设置（可选）
如果 SSH 配置生效后仍超时，可能是 VSCode 插件层面的限制。打开 VSCode 设置，搜索 remote.SSH.connectTimeout，适当增大该数值（单位秒）。

怎么验证是否生效

1. 打开 VSCode 远程资源管理器，尝试连接目标主机。
2. 连接成功后，保持窗口空闲不操作，观察 1-2 分钟。
3. 查看 VSCode 底部状态栏，若 SSH 图标未变灰且未弹出“连接丢失”提示，说明保活生效。
4. 如需查看详细日志，点击 VSCode 底部输出面板，选择“Remote - SSH”通道，确认无 timeout 相关报错。

常见坑

1. 文件权限错误
SSH 对配置文件权限要求严格，~/.ssh/config 权限应严格设置为 600。权限过开放会导致 SSH 客户端忽略该文件，可用 chmod 600 ~/.ssh/config 修复。

2. 配置缩进问题
SSH 配置文件对缩进敏感，选项行必须相对于 Host 行缩进（通常用空格或 Tab），否则可能无法识别。

3. 服务器端限制
部分服务器会在 /etc/ssh/sshd_config 中禁止客户端心跳（ClientAliveInterval），此时客户端配置可能无效，需联系服务器管理员确认。

参考来源

Visual Studio Code Docs, "Troubleshooting SSH", https://code.visualstudio.com/docs/remote/troubleshooting
OpenSSH, "ssh_config", https://man.openbsd.org/ssh_config