如何通过vscode连接远程服务器进行开发【教程】

VS Code 远程开发依赖 Remote – ssh 扩展，需服务器支持 SSH 和 VS Code Server；必须安装官方 microsoft 扩展，正确配置 ~/.ssh/config（含 User、Port、IdentityFile），确保私钥权限为 600；首次连接自动部署 vscode-server 到 ~/.vscode-server，需检查磁盘、挂载限制及权限；调试时路径须用远端绝对路径，避免 shell 配置输出干扰终端启动。

VS Code 连接远程服务器开发，核心靠 Remote - SSH 扩展，不是靠“配置 SSH 隧道再手动挂载”，也不是靠 scp 同步文件——那样既难调试又容易丢断点。只要服务器有 SSH 访问权限、能运行 VS Code Server（通常只要 linux/macOS + python 3.7+ 或 glibc 兼容），就能真正在远端执行代码、读日志、查进程。

装对扩展：只认 Remote - SSH，别装错名字

VS Code 市场里搜 “remote ssh” 会出现多个相似扩展，必须选官方出品、作者是 Microsoft、全名是 Remote - SSH 的那个。其他如 SSH FS 或 Remote SSH Editor 不支持调试器、终端集成和扩展自动同步，用它们等于退回 FTP 时代。

• 安装后重启 VS Code，状态栏右下角会出现 SSH TARGETS 图标
• 首次连接会自动在本地生成 ~/.ssh/config 条目，也支持直接编辑该文件复用已有配置
• 如果服务器禁用了密码登录（只允许密钥），确保本地 ssh-agent 已加载私钥：

  ssh-add -l

  能列出对应 key 才算就绪

ssh_config 里写清楚用户、端口、密钥路径，别依赖默认值

VS Code 的 Remote – SSH 默认读取 ~/.ssh/config，但很多人只写 Host xxx 和 HostName，漏掉关键字段，导致连接卡在 “Setting up SSH Host” 或报 Permission denied (publickey)。

• 必须显式指定 User，不能指望它猜（尤其当服务器默认 shell 是 /bin/bash 但用户家目录权限为 700 时）
• 如果服务器 SSH 端口不是 22，一定要加 Port 2222（比如阿里云安全组常改端口）
• 私钥路径用绝对路径，且确保权限是 600：

  chmod 600 ~/.ssh/id_rsa_myserver

• 推荐完整最小配置示例：

  Host myprod
    HostName 192.168.10.5
    User deploy
    Port 2222
    IdentityFile ~/.ssh/id_rsa_myserver
    StrictHostKeyChecking no

连接后别急着写代码：先确认 vscode-server 装在哪、有没有权限

首次连接时，VS Code 会在远端自动下载并解压 vscode-server 到 ~/.vscode-server。但如果用户家目录是 NFS 挂载、或 /tmp 被 noexec 挂载、或磁盘满，就会静默失败——现象是窗口左下角一直显示 “Installing VS Code Server…”，但实际没反应。

• 手动检查远端是否已部署：

  ls -la ~/.vscode-server/bin/

  应该有一串哈希命名的子目录

• 如果失败，可手动拉取（参考 VS Code 控制台里打印的真实下载 URL），解压到 ~/.vscode-server/bin/
• 若服务器禁止外网访问，需提前下载对应 commit 的 vscode-server-linux-x64.tar.gz，传上去再解压
• 注意：~/.vscode-server 必须属于当前登录用户，不能是 root 创建后 chown 过来——VS Code 启动时会校验 uid

调试 Python/node.js 时，路径映射和解释器位置最容易出错

本地打开的是远端项目，但 VS Code 的调试器仍运行在本地，所以 launch.json 中的 cwd、program、python 路径必须写远端真实路径，而不是你本地的镜像路径。

• 例如 Python 调试：不要写 "python": "./venv/bin/python"，而要写 "python": "/home/deploy/myproject/venv/bin/python"
• node.js 的 runtimeExecutable 如果指向 nvm 管理的 node，得用绝对路径：/home/deploy/.nvm/versions/node/v18.17.0/bin/node
• 源码映射（sourceMap）在前端项目中几乎必设，否则断点打不进 .ts 文件；后端服务如 fastapi 的 reload 模式下，也要关掉 --reload 再调试，否则进程反复启停导致调试器失联

最常被忽略的一点：远端的 .bashrc 或 .zshrc 里如果有 echo、printf 或 ANSI 转义字符输出，会导致 VS Code 启动 vscode-server 时解析失败，表现为连接成功但无法打开终端、插件不加载——删掉所有非必要输出，只保留 PATH、alias 等纯环境设置即可。