remote-ssh连接失败的核心原因是未理解其依赖远程vscode-server进程的机制。首次卡在“installing vs code server”多因服务器无法访问github下载包，需手动部署对应commit id的二进制文件并确保权限正确；ssh配置格式敏感、扩展未安装到远程、git/shell环境未适配、密钥权限或代理继承问题等均会导致各类异常。
Remote-SSH 不是“连上就完事”的功能，它实际在远程服务器上启动一个完整的服务进程（vscode-server），本地只负责渲染界面和转发输入。连不上、卡在“Installing VS Code Server”、扩展不生效、终端命令找不到——基本都源于没理清这个前提。
为什么 Remote-SSH 首次连接总卡在 “Installing VS Code Server”
这不是 VSCode 本身的问题，而是远程服务器无法完成 vscode-server 的自动下载和解压。VSCode 默认从 GitHub Releases 拉取二进制包，国内环境或受限网络下大概率失败。
- 检查服务器能否访问
https://update.code.visualstudio.com：在远程终端执行curl -I https://update.code.visualstudio.com，返回200才算通 - 若超时或拒绝连接，必须手动部署：
– 在本地 VS Code 关于窗口里复制 commit ID（形如6c3e3dba23e8fadc360aed75ce363ba185c49794）
– 去https://update.code.visualstudio.com/download?build=stable&os=linux-x64找对应 commit 的 tar.gz
– 解压后重命名文件夹为该 commit ID，上传到服务器的~/.vscode-server/bin/目录下
– 确保~/.vscode-server/bin/<commit-id>/bin/code-server</commit-id>可执行（chmod +x） - 别忽略权限：整个
~/.vscode-server目录必须属当前用户，且不能有 group/other 写权限（否则 server 启动失败）
~/.ssh/config 配置后 VSCode 不识别 Host 名
VSCode 会读取 ~/.ssh/config，但对格式极其敏感，错一个空格或漏一行都会导致主机名不显示在连接列表中。
-
Host行必须顶格写，后面不能跟空格或注释；HostName、User等子项必须缩进（用空格，不能用 Tab） - Host 别名不能含下划线（
my_server会被跳过），推荐用短横线（my-server） - 确保文件路径确实是
~/.ssh/config（不是~/.ssh/config.txt或其他位置），且权限为600（chmod 600 ~/.ssh/config） - 修改后无需重启 VSCode，但要重新触发“Connect to Host”命令面板，不能只点左下角图标刷新
扩展装了但 Python/Shell/Git 功能不工作
Remote-SSH 下的扩展分两类：本地运行的（如主题、快捷键管理）和远程运行的（如 Python、Pylance、GitLens）。后者必须明确安装到远程环境，否则根本不可见。
- 连接成功后，打开命令面板（
Ctrl+Shift+P），输入Extensions: Install Local Extension in SSH，再选你要的扩展 - 或者直接在扩展面板搜索，看到扩展右下角标着
Install on SSH: my-server才是对的；点它，而不是“Install” - Git 配置也得在远程生效：确保
git config --global user.name和user.email已设，且~/.gitconfig权限不是644以外的值（某些服务器策略会拒绝加载） - 终端默认使用远程 shell，但
PATH可能未加载完整（比如 zsh 的.zshrc没 source），可在~/.vscode-server/data/Machine/settings.json中加"terminal.integrated.env.linux": { "PATH": "/usr/local/bin:/usr/bin:/bin" }
连接成功但终端报 Permission denied (publickey)
这说明 VSCode 虽然走通了 SSH 连接流程，但后续子会话（比如新开终端、调试器启动）仍尝试用密码或错误密钥登录，本质是 SSH agent 没被正确继承。
- 确认私钥权限是
600：chmod 600 ~/.ssh/id_rsa（任何高于此权限，OpenSSH 都会静默拒绝） - 确保
~/.ssh/config中写了IdentityFile ~/.ssh/id_rsa，且路径准确（不要用~，写绝对路径更稳） - 如果用了带密码的私钥，VSCode 首次连接时会弹窗要求输入；若你跳过了或输错，后续所有子会话都会失败，此时需删掉
~/.ssh/known_hosts对应行并重连 - 服务器端检查
/etc/ssh/sshd_config是否禁用了密钥登录：PubkeyAuthentication yes必须启用，PasswordAuthentication no是安全推荐，但前提是密钥已配好
最常被忽略的一点：VSCode Remote-SSH 的“远程”是彻底的——你 Ctrl+S 保存的那一刻，文件就写进了服务器磁盘；你 Ctrl+` 开的终端，pwd 输出的是服务器路径；你设的断点，调试器 attach 的是服务器上的进程。别把它当成 FTP 同步工具，也不要用本地环境变量去猜远程行为。
