Remote-SSH连接失败需按五步排查：一、终端执行ssh命令验证基础连通性；二、检查~/.ssh/config语法及路径；三、确认远程sshd服务运行、用户主目录权限正确；四、清除本地与远程VSCode缓存；五、启用debug日志定位具体错误。
如果您尝试通过 VSCode 的 Remote-SSH 扩展连接远程服务器，但连接过程停滞、报错或直接断开，则可能是由于 SSH 配置、网络通路、认证机制或 VSCode 服务端组件异常所致。以下是排查此问题的步骤：
本文运行环境：MacBook Air M2，macOS Sequoia。
一、验证基础 SSH 连通性
Remote-SSH 依赖本地系统原生 SSH 客户端能力，若终端中无法直连，VSCode 必然失败。该步骤用于剥离 VSCode 干扰，确认底层连接是否可用。
1、打开终端，执行 ssh -T -p [端口号] [用户名]@[主机IP]（如未指定端口则省略 -p 参数）。
2、观察返回信息：若提示 Permission denied (publickey)，说明密钥认证失败；若提示 Connection refused，表明目标端口未监听或防火墙拦截；若超时无响应，需检查网络路由与目标主机存活状态。
二、检查 SSH 配置文件语法与路径
VSCode Remote-SSH 严格读取 ~/.ssh/config 文件中的 Host 块定义，任意格式错误（如缩进不一致、缺少换行、使用中文符号）均会导致解析中断并静默失败。
1、在终端中运行 ssh -F ~/.ssh/config -O check [Host别名]，验证配置可被正确加载。
2、用文本编辑器打开 ~/.ssh/config，确认 Host 块内无 Tab 字符混入，所有关键字（HostName、User、IdentityFile 等）后紧跟空格而非制表符，且 IdentityFile 路径为绝对路径（例如 /Users/yourname/.ssh/id_rsa）。
三、确认远程服务器 OpenSSH 服务与用户权限
VSCode 在首次连接时需在远程主机自动部署 server 启动脚本，该过程依赖标准 OpenSSH 服务、bash/sh 解释器及用户主目录写权限。任一缺失将导致连接卡在 “Installing VS Code Server” 阶段。
1、登录远程服务器后，执行 systemctl is-active sshd（Linux systemd 系统）或 service ssh status（传统 init 系统），确保服务处于 active 状态。
2、运行 ls -ld ~，确认当前用户对主目录拥有读、写、执行权限（即权限位包含 rwx）；若显示 dr-xr-xr-x，则需执行 chmod 700 ~ 修复。
四、重置 VSCode Remote-SSH 本地缓存与日志
VSCode 会缓存远程主机的 server 二进制、临时 socket 和连接元数据。缓存损坏常引发“已连接但无法加载窗口”或反复重试失败。
1、关闭所有 VSCode 窗口，在终端中执行 rm -rf ~/.vscode-server（远程主机上的缓存）和 rm -rf ~/.vscode-remote（本地记录）。
2、在 VSCode 中按 Cmd+Shift+P，输入 Remote-SSH: Kill VS Code Server on Host...，选择对应 Host，强制终止残留进程。
五、启用详细日志定位具体失败点
VSCode 默认日志级别不足以暴露底层 SSH 协议交互细节。开启 verbose 日志后，可在输出面板中查看完整握手流程与首个报错位置。
1、在 VSCode 设置中搜索 remote.ssh.logLevel，将其值设为 debug。
2、再次触发连接，在底部状态栏点击 “Remote Explorer”，右键目标 Host → Show Log，逐行查找含 stderr、Failed to parse 或 exit code 的行。
