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<br> HostName 192.168.10.5<br> User deploy<br> Port 2222<br> IdentityFile ~/.ssh/id_rsa_myserver<br> 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 等纯环境设置即可。
