Remote-SSH 让 VS Code 在本机显示编辑器,同时直接操作 Linux 服务器上的代码、终端和开发环境。项目文件留在服务器,运行与调试使用服务器资源,不需要每次修改后手动上传代码。

本文以 Windows 本机连接 Linux 服务器为例,围绕连接、环境选择、文件与端口访问、代理和排错展开。SSH 的密码与密钥配置见 Linux服务器SSH连接指南,服务器开发的整体流程见 AI Coding指南。

1 本地界面、远端 Server 与扩展的分工

Remote-SSH 的工作方式可以分成三部分:

  • 本地 VS Code负责窗口、编辑器界面,以及适合在本机运行的界面扩展。
  • 远端 VS Code Server在服务器用户目录中运行,提供文件、终端与远程开发服务。
  • 远端扩展宿主运行需要访问服务器项目和环境的扩展,例如语言分析与调试组件。

本机与远端组件通过 SSH 通道通信。打开远端文件夹后,保存文件会直接写入服务器;远端集成终端默认也在服务器执行命令。它不会自动维护一份相同的本地项目副本。

扩展的运行位置由其类型和实现决定,不能把“本机已安装扩展”理解为“远端环境也已就绪”。这也解释了为什么本机装有 Python、Git 或某个代理服务,远端任务仍可能找不到它们。Remote-SSH 官方说明

2 配置并验证连接

2.1 先验证命令行 SSH

在 Windows 本机 CMD 中执行:

1
ssh lab

这里的 lab 来自本机 %USERPROFILE%\.ssh\config。密码认证可使用如下配置:

1
2
3
4
5
6
Host lab
HostName server.example.edu
User alice
Port 22
ServerAliveInterval 30
ServerAliveCountMax 3

密钥认证在同一主机段中增加:

1
2
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes

示例地址、用户名与端口均需替换。私钥保留在本机,服务器登记对应公钥。使用带口令的私钥时,连接仍可能要求输入口令;已有本地 ssh-agent 可减少重复输入。跳板机则继续使用同一配置中的 ProxyJump。

2.2 连接远端窗口

在本机 VS Code 扩展面板安装 Microsoft 发布的 Remote - SSH(ms-vscode-remote.remote-ssh),然后:

  1. 按 Ctrl+Shift+P,执行 Remote-SSH: Connect to Host…。
  2. 选择 lab;首次询问平台时选择 Linux。
  3. 按提示输入账号密码或私钥口令,等待远端组件安装与启动。
  4. 确认窗口左下角显示 SSH: lab。
  5. 执行 File → Open Folder,打开服务器上的项目目录,例如 /home/alice/projects/demo。

密码与密钥认证使用相同的连接流程。首次部署组件或建立多个 SSH 连接时,可能重复出现认证提示。若界面一直等待却没有可见提示,在本地用户设置 JSON中合并:

1
2
3
{
"remote.SSH.showLoginTerminal": true
}

设置后重新连接,在登录终端中查看是否等待密码、验证码或主机指纹确认。参数用法见 Remote-SSH 认证排障。

2.3 确认实际执行位置

在这个远端窗口中新建终端,执行:

1
2
3
hostname
whoami
pwd

输出应对应服务器及目标项目目录。若终端仍显示 Windows 路径,先检查是否打开了本地窗口,或是否手动创建了本地终端。一个 VS Code 会话中可以同时存在本地与远端窗口,应以当前窗口的连接标记为准。

3 安装扩展与选择 Python 环境

3.1 把扩展安装在需要的位置

远端窗口的扩展面板会区分 Local 与 SSH: lab。Python、Jupyter 等开发扩展应按面板提示安装到远端;主题、图标等界面扩展通常留在本地。

扩展处于灰色禁用状态时,先检查是否需要 Install in SSH: lab。不必把本机所有扩展批量复制到服务器,也不应通过强制修改 remote.extensionKind 来修复所有扩展问题;某些扩展只能在其设计的位置运行。

3.2 选择服务器上的解释器

打开远端项目后,执行 Python: Select Interpreter,选择该项目实际使用的 Conda 或虚拟环境。例如:

1
2
/home/alice/miniconda3/envs/research/bin/python
/home/alice/projects/demo/.venv/bin/python

这些是服务器路径,不能填写本机的 C:\...\python.exe。若列表中没有已存在的环境,可选择输入解释器路径,并先在远端终端确认该文件存在。

选择解释器后,新建一个远端终端并验证:

1
2
python -c "import sys; print(sys.executable)"
python -m pip --version

第一条显示实际执行的 Python,第二条显示该解释器对应的 pip。两者路径应属于预期环境。使用 python -m pip 可减少 pip 命令指向另一套环境的情况。

扩展通常会在新终端中激活选中的环境,但已有终端不一定随之切换。如果终端输出不符,检查自动激活设置,或在该终端手动执行已有环境的激活命令:

1
2
conda activate research
# 使用项目 .venv 时,改为:source .venv/bin/activate

解释器选择会影响语言分析、运行与调试;已有调试配置若单独指定解释器,则还需检查该配置。环境选择和终端激活机制见 VS Code Python 环境文档。

3.3 Notebook 的内核需要单独确认

打开 .ipynb 后,通过右上角的内核选择器选择服务器上的目标环境。在单元格中运行以下代码,可确认 Notebook 实际使用的解释器:

1
2
import sys
print(sys.executable)

终端已激活某个环境,不代表已有 Notebook 自动切换内核。调试、终端与 Notebook 出现不同导入结果时,先比较解释器路径,再判断是否缺少依赖。

4 打开已有 Git 项目

通过 Open Folder 打开服务器上的仓库根目录,而不是只打开其中一个脚本。在远端终端检查:

1
2
3
4
git --version
git rev-parse --show-toplevel
git status --short
git remote -v

这些命令分别确认远端 Git 可用、当前仓库根目录、工作区改动和远程仓库地址。源代码管理面板操作的是这份服务器仓库,编辑后可直接查看差异,再按项目流程暂存与提交。VS Code 源代码管理说明

若提示“不在 Git 仓库中”,先确认打开的目录是否正确,不要直接在错误目录执行 git init。仓库已经存在时,也无需再克隆一份来让 VS Code 识别。

连接服务器的 SSH 凭据与服务器访问 Git 托管平台的凭据是两件事。ssh lab 成功,不代表远端 git pull 或 git push 必然成功;应检查远程 URL 使用 HTTPS 还是 SSH,并按托管平台与服务器的既有方式配置认证。

数据集、权重、日志和个人密钥不应因为远程开发而自动加入版本管理。已有仓库的 .gitignore、分支与未提交改动仍按原项目管理。

5 用端口转发访问远端 Web 工具

网页应用在服务器运行时,其 127.0.0.1 指向服务器;本机浏览器中的 127.0.0.1 指向 PC。SSH 端口转发把两端连接起来,无需为临时开发页面直接开放服务器公网端口。

以预览项目中的静态结果页面为例,在远端终端进入仅包含待预览内容的目录:

1
2
cd ~/projects/demo/reports
python -m http.server 8000 --bind 127.0.0.1

目录需事先存在。该命令提供当前目录的文件列表与文件内容,适合临时预览;不要在包含密钥或私有配置的目录启动。命令参数见 Python HTTP Server 文档。

随后在 VS Code 中:

  1. 打开底部 Ports 面板,必要时执行 Ports: Focus on Ports View。
  2. 选择 Forward a Port 或添加端口,输入远端端口 8000。
  3. 查看生成的 Forwarded Address,从本机浏览器打开该地址。

如果本机 8000 已占用,实际分配的本地端口可能不同,例如 http://127.0.0.1:4123;以面板显示值为准。Jupyter、TensorBoard 等工具也可以转发其监听端口,工具本身的登录令牌或认证设置仍然有效。Remote-SSH 端口转发说明

关闭转发不等于停止远端服务,终止远端服务则会使转发地址失去响应。临时测试结束后,在服务终端按 Ctrl+C,并按需移除 Ports 中的转发记录。

6 分清组件下载与代理配置

6.1 本机下载 VS Code Server

首次连接或本机 VS Code 更新后,远端可能需要相应版本的 Server。Remote-SSH 默认尝试远端下载,失败时可回退到本机下载再传输。服务器下载较慢、本机线路可用时,可在本地用户设置 JSON中合并:

1
2
3
{
"remote.SSH.localServerDownload": "always"
}

它改变的是 VS Code Server 的下载位置。远端扩展、扩展额外下载的语言服务、模型或其他依赖,不会因此全部改由 PC 下载。Remote Development 联网要求

6.2 本地 VS Code 的代理

VS Code 的多数界面请求会使用系统代理。需要显式配置时,可在本地用户设置中加入本机已有 HTTP 代理地址:

1
2
3
{
"http.proxy": "http://127.0.0.1:7890"
}

这里的 7890 必须是 PC 上真实运行的代理端口。http.proxySupport 控制扩展代理支持,可保留默认设置;http.proxy 并非接管所有程序网络的总开关,个别扩展和下载器仍可能使用自己的网络栈。VS Code 网络与代理说明

6.3 远端扩展的代理

远端扩展发起的连接,需要服务器可达的代理。若按 Linux服务器代理联网指南 在服务器启动了 Mihomo,可在当前远端窗口的设置中切换到 Remote [SSH: lab],合并:

1
2
3
4
{
"http.useLocalProxyConfiguration": false,
"http.proxy": "http://127.0.0.1:7890"
}

这里的 127.0.0.1:7890 是服务器上的代理,即使文字与本地设置相同,也不是同一项服务。只有 PC 运行代理时,不能直接把该地址当成服务器可用代理;需要先建立合适的 SSH 转发,或在服务器部署代理。

http.useLocalProxyConfiguration 决定远端扩展宿主是否采用本地代理配置。关闭后,才能分别配置远端代理。当前官方排障文档明确给出了这一处理方式,不能简单概括成“本地设置始终继承”或“本地设置绝不继承”。远端扩展联网排障

命令行工具还需各自支持并读取 http_proxy、https_proxy 等环境变量。在已有集成终端中执行 export,只影响该终端及后续子进程,不会追溯改变已经启动的 VS Code Server。需要让 Server 读取环境变量时,应在其启动环境配置,并在保存工作后重启相应远端组件。

7 按阶段定位连接故障

7.1 命令行也无法连接

先回到本机 CMD 测试 ssh lab。如果仍失败,检查网络、端口、账号、主机指纹和密钥配置,处理方法见 SSH连接指南。此时重装 VS Code 扩展通常不能解决基础连接问题。

7.2 CMD 成功,但 VS Code 失败

打开 View → Output,选择 Remote - SSH,或执行 Remote-SSH: Show Log。先看它实际使用的 SSH 程序、配置文件、目标账号与报错阶段。

在本机 CMD 可用 where ssh 查看候选客户端。如果 VS Code 读取了另一份配置,可在本地用户设置中明确指定:

1
2
3
{
"remote.SSH.configFile": "C:/Users/你的用户名/.ssh/config"
}

路径应改成实际文件位置。日志若停在认证阶段,启用 remote.SSH.showLoginTerminal;若已经完成认证,再检查 Server 下载、解压和启动。日志可能含用户名、内部地址与本地路径,公开求助前应移除这些信息。

7.3 Server 无法安装或启动

在普通 SSH 终端检查:

1
2
3
4
5
6
uname -m
uname -r
ldd --version
df -h "$HOME"
df -i "$HOME"
command -v bash tar curl wget

当前官方 Linux 基础要求包括内核 4.18 及以上、glibc 2.28 及以上、libstdc++ 提供 GLIBCXX_3.4.25,以及 tar;Remote-SSH 还需要 SSH 服务、Bash,并提供 curl 或 wget。3.4.25 是 libstdc++ 符号版本,不能仅用 GCC 编译器版本代替判断。要求会随版本演进,具体见 Linux 远程开发前置条件。

磁盘空间、inode 或用户配额耗尽会导致写入失败;noexec 挂载和启动脚本强制切换 Shell 也可能影响组件运行。若系统版本不满足要求,应使用受支持的服务器环境或与管理员协商,不能在个人账号下直接替换系统 glibc。

7.4 SSH 登录正常,但隧道失败

日志中的 administratively prohibited 可能表示服务器限制了 SSH 转发。Remote-SSH 依赖相关通道,普通 Shell 能登录不代表所有转发都被允许。应向管理员确认具体限制;HTTP 代理配置不能替代 SSH 服务端的转发权限。

7.5 已连接,但扩展异常或窗口反复重连

先查看对应扩展的 Output 通道和 Log (Remote Extension Host),确认是否只有某个扩展失败。可以先禁用最近新增的相关扩展,再重新加载窗口;远端仍可能受内存、磁盘和架构兼容性影响。

只有在日志指向远端组件状态异常时,再保存未保存的工作、确认相关终端任务状态,考虑执行 Remote-SSH: Kill VS Code Server on Host… 并重新连接。它会影响该账号的相关远端连接。删除整个 ~/.vscode-server 会涉及已安装组件与用户状态,不应作为每次排错的默认步骤。更多定位方法见 Remote Development 官方排障文档。