VSCode 远程开发实战：Remote-SSH 配置与连接排错

什么场景值得上远程开发

三种典型场景：① 代码必须留在内网（合规限制无法同步到本地）；② 重活靠远端算力（训练、编译、大规模测试），本地只负责编辑；③ 本地环境跑不起依赖（Linux-only 工具链）。Remote-SSH 的原理是把 VSCode Server 部署到远端 ~/.vscode-server，UI 渲染在本地、语言服务与终端在远端执行——所以打开大仓库也不吃本地内存。

# 安装：扩展市场搜索 "Remote - SSH"（ms-vscode-remote.remote-ssh）

三步连接：host、免密、选平台

① 把服务器写进 ~/.ssh/config（别名 + 用户 + 密钥），Remote-SSH 会直接读取这个文件供你选择；② 先在终端手动 `ssh 别名` 验证免密可用（顺手把密钥配好，见 SSH 免密指南）——这一步能提前排掉 90% 的连接问题；③ 在 VSCode 命令面板执行 Remote-SSH: Connect to Host，首次连接会自动下载对应平台的 vscode-server。

跳板机场景在 config 里用 ProxyJump 一行解决，无需手工双跳。

Host gpu-box
  HostName 10.0.0.8
  User dev
  IdentityFile ~/.ssh/id_ed25519
  ProxyJump bastion.corp.internal   # 跳板机一行搞定

连不上时的五步排查

① 终端裸连 `ssh 别名` 是否正常——不正常就先修 SSH 层（权限/密钥/网络），别在 VSCode 里瞎试；② 远端磁盘是否写满：vscode-server 要往 ~/.vscode-server 写几百 MB，磁盘满时连接卡在 "Setting up SSH Host"；③ ~/.vscode-server 损坏（升级中断、架构不符）：删除该目录重连让它重装；④ 远端 glibc 太老：旧系统（CentOS 7 之前的更老系统）跑不动新版 server，锁定旧版本 VSCode 或升级系统；⑤ 端口转发失败：本地代理/VPN 占用或防火墙拦 CDP 端口。

df -h ~                       # 远端磁盘是否写满
rm -rf ~/.vscode-server       # 损坏时重置（重连自动重装）

体验优化：扩展、端口与 Git

扩展分本地端与远端端：语言类（Python/ESLint）要「Install in SSH: xxx」装到远端，主题图标类留在本地。开发服务器起在远端端口后，用「端口」面板一键 Forward 到 localhost，浏览器直接访问 localhost:3000 就等于访问远端服务——调试联调的核心便利。

Git 在远端跑，提交鉴权走远端的凭据（远端配 SSH key 或 credential helper），与本地的 GitHub 登录无关——配错位置是「为什么推送总 403」的头号原因。

# 命令面板常用：
Remote-SSH: Connect to Host
Forward Port...            # 远端端口映射到本地
Install in SSH: <host>    # 扩展装到远端

和裸 SSH + vim 怎么选

Remote-SSH 适合「写代码为主」的日常：完整 IDE 能力（跳转、重构、调试器）+ 远端算力。服务器只有几百 MB 余量、或临时救火改两行配置时，直接 ssh + vim/微编辑器更轻。两者不冲突：vscode-server 磁盘紧张时删掉即可完全回退，不留残余。

du -sh ~/.vscode-server   # 看远端 server 占用
rm -rf ~/.vscode-server   # 完全卸载（下次重连会重新下载）

收尾清单

config 写别名 → 终端验证免密 → Connect to Host → 语言扩展装远端 → 端口转发调试 → Git 凭据配在远端。这六步配完，远程开发体验与本地几乎无差别；遇到连接问题先回终端裸连定位层级，再处理 vscode-server 层。

ssh 别名 && code .   # 免密就绪后，一条命令进入远程开发