VSCode Remote-SSH 断连主因是客户端未配置 SSH 心跳，需同时设置 ServerAliveInterval 和 ServerAliveCountMax；服务端需配 ClientAliveInterval 与 ClientAliveCountMax；VSCode 应启用 useLocalServer 并检查日志确认配置生效。
客户端配置 SSH 心跳：ServerAliveInterval 和 ServerAliveCountMax 必须配对用
VSCode Remote-SSH 断连，90% 是因为本地 SSH 客户端根本没发心跳包——不是服务器“不给活”，是你没告诉它“我还在线”。ServerAliveInterval 控制发送间隔（单位秒），ServerAliveCountMax 控制容忍丢包次数，两者缺一不可。
常见错误现象：
- 改了
ServerAliveInterval但没设ServerAliveCountMax，结果一丢包立刻断开 - 在命令行用
ssh -o ServerAliveInterval=60 user@host临时连接，却忘了加-o ServerAliveCountMax=3 - 把配置写在
~/.ssh/config里，但 Host 别名写错了（比如用了 IP 而非 HostName），导致配置未生效
实操建议：
- 编辑
~/.ssh/config，添加通用规则：Host *
ServerAliveInterval 60
ServerAliveCountMax 3 - 若只针对某台主机，用具体别名更安全：
Host prod-server
HostName 10.0.2.5
User ops
ServerAliveInterval 45
ServerAliveCountMax 5 - 参数差异：
ServerAliveInterval 60表示每分钟探一次；ServerAliveCountMax 3意味着最多容忍 3 分钟无响应——超时后客户端主动断开，避免卡死
服务端配置 SSH 心跳：ClientAliveInterval 不等于客户端的“镜像”
服务端的 ClientAliveInterval 和 ClientAliveCountMax 看似和客户端对称，但作用对象相反：它是服务器主动探测“你还在不在”，不是转发你的心跳。很多运维误以为只要客户端配了，服务端就不用动，结果中间防火墙或云厂商 NAT 网关照样掐断连接。
使用场景：
实操建议：
- 编辑
/etc/ssh/sshd_config，取消注释并设置：ClientAliveInterval 300
（即每 5 分钟探一次，两次失败后断开）
ClientAliveCountMax 2 - 不要盲目抄 “60+3”：服务端间隔太短（如 30 秒）会增加无效流量；太大（如 1800 秒）则起不到保活作用
-
ClientAliveInterval仅对协议 v2 生效，且必须配合TCPKeepAlive yes（默认已开启）才可靠 - 改完务必执行
sudo systemctl restart sshd，否则配置不生效
VSCode Remote-SSH 插件的隐藏开关：remote.ssh.useLocalServer 影响隧道稳定性
VSCode Remote-SSH 不是直接复用你的终端 SSH 连接，而是启动一个独立的 SSH 隧道进程。这个进程如果被系统休眠、资源限制或插件自身 Bug 干扰，就会静默掉线——此时即使 SSH 配置全对，也救不了。
容易踩的坑：
- 禁用
remote.ssh.useLocalServer（默认关闭），会让 VSCode 在远程机器上起一个代理服务，反而增加一层故障点 -
remote.ssh.pathTimeout默认是 15000 毫秒，遇到高延迟网络（如跨国跳板机）会直接报 “Failed to connect before timeout” - Windows 用户用 WSL2 作为本地环境，却没在 WSL2 的
~/.ssh/config里配心跳，只配了 Windows 的，结果无效
实操建议：
- 在 VSCode 设置中搜索
remote.ssh.useLocalServer，✅ 勾选启用（让隧道走本地 SSH 客户端逻辑） - 将
remote.ssh.pathTimeout改为30000或更高，避免路径解析阶段因网络抖动失败 - 确认 VSCode 读的是哪个
~/.ssh/config：打开 Remote-SSH 日志（Ctrl+Shift+P→ “Remote-SSH: Show Log”），看它加载的配置路径
TCPKeepAlive 和加密心跳的区别：别让防火墙当“中间人”截断
很多人以为开了 TCPKeepAlive yes 就万事大吉，其实这是个底层 TCP 保活机制，数据包不加密、无认证，容易被企业级防火墙识别为“无效探测”而丢弃。而 ServerAliveInterval 发的是加密通道内的 SSH 协议心跳，防火墙无法干预。
性能与兼容性影响：
-
TCPKeepAlive开销极低，但不可靠；ServerAliveInterval有轻微加密开销，但穿透性强 - 某些老旧嵌入式设备 SSH 实现不支持加密心跳，只能依赖
TCPKeepAlive，此时需和服务端ClientAliveInterval协同调优 - 云服务器厂商（如 AWS EC2）明确建议优先使用 SSH 层心跳，而非 TCP 层
实操建议：
- 客户端配置中保留
TCPKeepAlive yes作为兜底，但不依赖它保活 - 若发现日志里频繁出现
Write failed: Broken pipe，大概率是 TCP 层被掐断，此时要检查ServerAliveInterval是否生效，而不是调大TCPKeepAlive时间 - 真正关键的，是客户端和服务端的两个“Alive”参数形成闭环：客户端发，服务端回；服务端探，客户端应
最常被忽略的一点：VSCode Remote-SSH 的日志里会明确打印出它实际使用的 SSH 命令行，包括所有 -o 参数。如果你改了 ~/.ssh/config 却没生效，第一反应不该是重装插件，而是打开日志，看它到底有没有读到你写的那几行。
