VS Code Remote-SSH 连接失败主因是 SSH 配置未被识别、远程机器不满足运行条件或 VS Code Server 部署失败；须确认 sshd 启用、端口放行、密钥权限正确、host key 手动确认，并重启 VS Code；首次连接需确保远程可访问 update.code.visualstudio.com、有 curl/wget、磁盘充足且 /tmp 可执行；环境变量需写入 ~/.profile 或通过 SetEnv 配置，Python 解释器须用绝对路径指定。
VS Code 通过 Remote-SSH 扩展连接远程服务器不是“配好就能用”，关键在于 SSH 配置是否被正确识别、目标机器是否满足最低运行条件，以及 VS Code Server 是否能自动部署成功。
确认远程服务器已启用 SSH 并可本地命令行直连
这是最常被跳过的前置步骤。如果在终端里执行 ssh user@host 都失败，Remote-SSH 必然无法工作。
- 确保远程机器运行着
sshd服务（Linux/macOS 常见；Windows 需启用 OpenSSH Server） - 检查防火墙是否放行了
22端口（或你自定义的 SSH 端口） - 若使用密钥登录，确认私钥权限为
600（chmod 600 ~/.ssh/id_rsa），否则 VS Code 会静默拒绝 - 首次连接时终端弹出的 host key 确认提示（yes/no）必须手动确认过，否则 Remote-SSH 可能卡在“Setting up SSH Host”
Remote-SSH 扩展安装后必须重启 VS Code 窗口
装完扩展不重启，Ctrl+Shift+P 里搜不到 Remote-SSH: Connect to Host... 是正常现象 —— 扩展需要完整加载 VS Code 的远程协议栈。
- 安装
Remote - SSH后，点击右下角绿色状态栏 → 选择Remote-SSH: Connect to Host...（不是“Open Folder in Container”之类） - 首次连接会引导你编辑
~/.ssh/config；如果已有配置，务必保证格式严格：每段以Host开头，HostName、User不可缺失，别用注释隔开关键行 - 配置示例中禁止出现中文路径、空格未转义、缩进不一致等问题，否则 VS Code 解析失败且无明确报错
连接后 VS Code Server 下载失败的典型原因
VS Code 在远程首次启动时，会在用户家目录下自动解压并运行一个轻量版服务端（vscode-server）。下载失败会导致“Installing VS Code Server” 卡住或报 Failed to fetch。
- 远程机器不能完全离线：它需要能访问
update.code.visualstudio.com（国内用户常因网络策略失败） - 若远程无
curl或wget，安装会中断；建议提前在远程执行which curl或which wget - 磁盘空间不足（尤其
/tmp或家目录）会导致解压失败，错误日志藏在~/.vscode-server/cli/servers/...子目录中 - 非 root 用户但
/tmp被挂载为noexec，也会导致启动脚本无法执行 —— 此时需设置环境变量VSCODE_AGENT_FOLDER指向可执行目录
文件系统权限与扩展同步问题
Remote-SSH 默认只同步“已启用”的扩展，但某些扩展（如 Python、Prettier）依赖远程环境中的二进制工具（python、prettier），它们必须在远程 PATH 中可用。
- 远程的
~/.bashrc或~/.zshrc中添加的export PATH=...不一定被 VS Code Server 加载；建议把 PATH 修改写入~/.profile或在~/.ssh/config中加SetEnv配置 - 本地安装的扩展不会自动出现在远程侧 —— 进入远程窗口后，需在 Extensions 视图中勾选
Show Installed Extensions，再手动启用 - 若远程 Python 环境使用虚拟环境，务必在 VS Code 中通过
Python: Select Interpreter指向绝对路径（如/home/user/venv/bin/python），相对路径会失效
Host myserver
HostName 192.168.1.100
User alice
IdentityFile ~/.ssh/mykey
ForwardAgent yes
ServerAliveInterval 60真正卡住的地方往往不是连接本身，而是 VS Code Server 在远程启动那一刻的上下文 —— 它不继承你日常终端的所有环境变量，也不保证和你的 shell 初始化逻辑一致。调试时优先看 Output 面板中 Remote-SSH 和 Log (Remote Server) 两个通道的日志，比反复重连更有效。
