VS Code Remote-SSH 实际运行远程 VS Code Server，本地仅为图形界面；连不上、卡顿、权限报错、扩展失效多因未理解此前提。需确保 SSH 密钥无密码直连、~/.ssh/config 配置正确、私钥权限为600、服务器可访问 GitHub 或手动部署 server binary，并注意路径、shell 环境、git 配置及远程扩展设置。
VS Code 的 Remote - SSH 扩展不是“能连上就行”的玩具，它实际运行的是远程机器上的 VS Code Server，本地只是个图形壳——这意味着你的代码、终端、调试器、甚至 git 都在服务器上执行。连不上、卡顿、权限报错、扩展不生效，90% 都源于没理清这个前提。
确认 SSH 服务和密钥已就绪
Remote - SSH 不走密码登录（除非你手动配），它依赖系统级 SSH 配置。先确保你在本地能无密码直连：
- 用
ssh -T user@host测试是否通，出现Permission denied (publickey)就别往下走 -
~/.ssh/config中的 Host 别名必须唯一，且不能含下划线（my_server会失败，改用my-server） - 私钥文件权限必须是
600（chmod 600 ~/.ssh/id_rsa），否则 OpenSSH 直接拒绝加载 - 如果服务器禁用了密码登录（
PasswordAuthentication no），而你又没配好密钥，VS Code 会卡在“正在安装 VS Code Server”并超时
安装 Remote - SSH 并触发首次连接
装完扩展后，不要点左下角“Remote Explorer”图标盲目选主机——它不会自动读取 ~/.ssh/config 里的别名，得手动触发：
- 按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Remote-SSH: Connect to Host... - 如果列表为空，说明 VS Code 没扫描到有效配置；检查
~/.ssh/config文件是否在用户主目录、是否可读、是否有语法错误（比如漏了Host或缩进不对） - 首次连接时，VS Code 会在服务器
~/.vscode-server下下载对应版本的 server binary，若服务器无法访问 GitHub 或国内网络受限，会卡住或报Failed to fetch download URL——此时需手动下载并上传（见下一条）
手动部署 VS Code Server（离线/受限环境必需）
服务器没外网时，VS Code 无法自动拉取 server，但你可以绕过：
- 去 https://update.code.visualstudio.com 找对应 commit ID 的 tar.gz（commit ID 在本地 VS Code 关于窗口里能看到，形如
6c3e3dba23e8fadc360aed75ce363ba185c49794） - 解压后得到
vscode-server-linux-x64目录，重命名为06c3e3dba23e8fadc360aed75ce363ba185c49794（即 commit ID） - 上传到服务器的
~/.vscode-server/bin/下（路径不存在就mkdir -p） - 确保该目录属主是当前用户，且
bin下有可执行的node和code-server - 再连一次，VS Code 就跳过下载，直接启动
常见断连与扩展失效问题
连上了但插件不工作、终端打不开、Ctrl+P 搜不到文件？大概率是路径或权限链断了：
- 打开的文件夹路径必须是服务器上真实存在的绝对路径（如
/home/user/project），不能是符号链接开头的路径（/data → /mnt/nvme/data这种会失败） - 远程终端默认使用
$SHELL，但如果你的 shell 是zsh且~/.zshrc里有交互式判断（[[ -t 1 ]]），会导致 VS Code 终端初始化失败——删掉或注释掉相关逻辑 - Git 提交失败报
unable to access '...': Could not resolve host？不是代理问题，而是 VS Code Server 启动时没继承你的 shell 环境变量，需在~/.bashrc或~/.zshenv里设export GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no"等必要变量 - 扩展装在远程却提示“已禁用”，检查服务器上
~/.vscode-server/data/Machine/settings.json是否有"extensions.ignoreRecommendations": true这类限制项
真正麻烦的从来不是“怎么连上”，而是连上之后，你的开发环境是否等价于在服务器上开一个原生终端再跑 VS Code —— 任何偏离这点的设计（比如把本地 shell 配置硬塞进远程、或指望 GUI 程序在无桌面环境下弹窗），都会在某个深夜突然崩掉。
