【Linux VSCode Remote-SSH 远程连接Linux服务器完整教程｜2026最新版 零基础免密登录+全场景排坑】

VSCode Remote-SSH 远程连接Linux服务器完整教程｜2026最新版 零基础免密登录+全场景排坑

前言

在后端开发、Linux运维、项目部署等日常工作中，传统终端工具（Xshell、FinalShell）仅支持命令行操作，无法实现可视化文件编辑、代码调试与项目目录管理，频繁的FTP上传下载也会大幅降低开发效率。

VSCode 官方推出的 Remote-SSH 插件，可让本地 VSCode 直接连接远程 Linux 服务器，将服务器目录映射为本地工作区，支持在线编辑代码、集成终端、断点调试、插件扩展等完整IDE能力，无需文件中转，真正实现“本地开发、远端运行”的无缝体验。

本文基于 2026 年最新稳定版 VSCode 与官方 Remote-SSH 插件编写，覆盖零基础入门→免密配置→高阶用法→全量排错全流程，针对国内用户补充了服务端加速、Windows 环境兼容、企业内网跳板机等高频场景方案，新手按步骤操作可一次配置成功。

---

一、前置环境准备

1.1 本地环境要求

• 已安装正式版 VSCode（建议升级至最新稳定版，避免版本兼容问题）
• Windows 10 1809 及以上 / Windows 11 / macOS / Linux 系统
• Windows 系统需启用「OpenSSH 客户端」（系统自带，无需额外下载）

1.2 服务器端要求

• 任意 Linux 发行版服务器（云服务器、虚拟机、内网物理机均可）
• 服务器已开启 SSH 服务（默认监听 22 端口）
• 防火墙、云服务器安全组已放行 SSH 对应端口
• 拥有服务器合法登录权限（用户名+密码 或 SSH密钥）

1.3 核心工作原理

Remote-SSH 采用客户端-服务端架构：

• 本地 VSCode 仅负责界面展示与交互输入
• 首次连接时会自动在服务器安装 vscode-server 服务端程序
• 所有代码解析、插件运行、命令执行均在服务器端完成，本地仅传输界面指令与文件增量
• 相比传统 FTP+终端 方案，避免了文件来回同步，大幅降低环境不一致导致的出错概率

---

二、安装 Remote-SSH 官方插件

1. 打开 VSCode，点击左侧侧边栏 扩展（Extensions） 图标（快捷键 Ctrl+Shift+X）
2. 在搜索框输入 Remote - SSH，找到微软官方（Microsoft）发布的插件
3. 点击「安装」，等待几秒即可完成，安装后无需重启 VSCode
4. 安装成功后，左侧侧边栏会出现 远程资源管理器 图标（电脑形状标识），代表插件生效

💡 小贴士：请勿安装第三方同名插件，认准发布者为 Microsoft，避免安全与兼容风险。

---

三、基础连接：密码登录方式

3.1 打开 SSH 配置文件

1. 点击左侧「远程资源管理器」图标
2. 顶部下拉菜单选择 SSH 选项
3. 点击 SSH 栏右侧的 齿轮（设置） 图标
4. 在弹出的配置文件选择框中，选择用户目录下的默认配置文件：
   • Windows：C:\Users\你的用户名\.ssh\config
   • macOS/Linux：~/.ssh/config
     点击后即可进入配置文件编辑界面。

3.2 编写 SSH 连接配置

在 config 文件中填写以下配置模板，替换为你的服务器真实信息：

# 自定义服务器别名，可随意命名，用于本地识别
Host aliyun-linux
  # 服务器公网IP地址（内网服务器填内网IP）
  HostName 120.79.xxx.xxx
  # 服务器登录用户名，云服务器默认通常为 root
  User root
  # SSH 服务端口，默认22，若修改过端口请填写对应端口号
  Port 22

核心参数说明

• Host：本地自定义的服务器名称，不影响实际连接，用于多服务器场景下快速区分
• HostName：服务器的真实可访问 IP 地址，必须准确无误
• User：服务器系统的登录用户名，需与实际账号一致
• Port：SSH 服务监听端口，默认 22，若服务器自定义过端口必须同步修改

编辑完成后按 Ctrl+S 保存配置文件。

3.3 首次连接服务器

1. 回到远程资源管理器的 SSH 列表，即可看到刚配置的服务器别名
2. 鼠标悬停在服务器名称上，点击右侧出现的 「在新窗口中连接」 图标
3. 首次连接会弹出操作系统选择框，选择对应服务器系统（绝大多数为 Linux）
4. 弹出密码输入框时，输入服务器登录密码并回车
5. 等待 VSCode 自动在服务器端安装 vscode-server 依赖，首次安装约 10~60 秒

当 VSCode 左下角状态栏出现 SSH: 服务器别名 的绿色标识时，代表远程连接成功。

3.4 打开远程工作目录

1. 连接成功后，点击顶部菜单栏「文件 → 打开文件夹」
2. 输入服务器上的目标目录路径，例如 /root、/home/project
3. 点击确定后，左侧资源管理器即可加载服务器对应目录的所有文件
4. 直接在编辑器中修改文件，保存后会自动同步到服务器，无需额外上传操作

---

四、进阶配置：SSH 密钥免密登录（推荐）

每次连接输入密码效率低且存在暴力破解风险，配置 SSH 密钥对可实现一键免密登录，同时安全性远高于密码登录，是生产环境的标准方案。

4.1 密钥登录原理

采用非对称加密验证机制：

• 本地生成一对密钥：公钥（public key） 和 私钥（private key）
• 公钥上传到服务器的授权列表中，私钥仅保留在本地
• 连接时服务器通过公钥验证本地私钥身份，验证通过直接登录，无需输入密码
• 私钥等同于登录凭证，请勿泄露或上传到公共平台

4.2 本地生成密钥对

Windows 系统前置步骤：启用 OpenSSH 客户端

Windows 10 1809+ / Win11 系统自带 OpenSSH 客户端，默认可能未启用，需先开启：

1. 按下 Win+I 打开系统设置，进入「应用 → 可选功能」
2. 搜索「OpenSSH 客户端」，若未安装则点击「添加功能」，找到并安装
3. 安装完成后，CMD 或 PowerShell 即可正常使用 ssh-keygen 命令

生成密钥命令

1. 打开本地终端（Windows 用 PowerShell 或 CMD，macOS/Linux 用系统终端）
2. 执行生成命令，推荐使用 4096 位长度提升安全性：

ssh-keygen -t rsa -b 4096

3. 命令执行后会提示保存路径，直接回车使用默认路径即可
4. 提示设置密钥密码时，直接回车留空即可（若设置密钥密码，连接时仍需输入密钥密码）
5. 执行完成后，密钥对会生成在默认目录：
   • Windows：C:\Users\用户名\.ssh\
   • macOS/Linux：~/.ssh/
   • 其中 id_rsa 为私钥文件，id_rsa.pub 为公钥文件

4.3 将公钥上传到服务器

方式1：命令一键上传（macOS/Linux / Windows Git Bash 可用）

类 Unix 终端可直接使用 ssh-copy-id 一键完成公钥上传与配置：

ssh-copy-id 用户名@服务器IP地址

输入一次服务器登录密码，公钥会自动追加到服务器的 ~/.ssh/authorized_keys 文件中。

💡 说明：Windows 原生 CMD / PowerShell 不自带 ssh-copy-id 命令，可使用 Git Bash 执行，或用下方手动方式上传。

方式2：手动上传（全系统通用，新手推荐）

1. 打开本地公钥文件 id_rsa.pub，复制文件内的全部内容
2. 登录服务器，执行以下命令创建 SSH 目录（若已存在则跳过）：

mkdir -p ~/.ssh

3. 将公钥内容写入服务器的授权文件：

echo "你复制的公钥内容" >> ~/.ssh/authorized_keys

4. 设置正确的文件权限（关键步骤，权限错误会直接导致免密失效）：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

4.4 验证免密登录

配置完成后，回到 VSCode 重新连接服务器，无需输入密码即可直接登录，代表配置成功。

若仍提示输入密码，大概率是服务器端文件权限错误，或公钥内容粘贴有误，可参考文末报错排查部分解决。

---

五、高阶配置与实用技巧

5.1 多服务器批量管理

在 config 文件中依次添加多个 Host 配置块，即可在 VSCode 中统一管理多台服务器，一键切换：

Host aliyun-prod
  HostName 120.79.xxx.xxx
  User root
  Port 22

Host tencent-test
  HostName 101.33.xxx.xxx
  User ubuntu
  Port 22

Host local-vm
  HostName 192.168.1.100
  User dev
  Port 22

5.2 跳板机（代理）连接配置

企业内网服务器通常无法直连，需要通过跳板机中转，可在 config 中通过 ProxyCommand 配置，无需手动先登录跳板机：

# 跳板机配置
Host jump-server
  HostName 跳板机公网IP
  User 跳板机用户名
  Port 22
  IdentityFile ~/.ssh/id_rsa

# 目标内网服务器
Host inner-server
  HostName 目标服务器内网IP
  User 目标服务器用户名
  Port 22
  # 通过跳板机中转连接
  ProxyCommand ssh -W %h:%p jump-server

配置完成后可直接连接内网服务器，VSCode 会自动通过跳板机完成链路中转。

5.3 解决 vscode-server 下载慢/安装失败

国内服务器常因网络问题导致 vscode-server 下载超时、安装卡住，可通过以下两种方案解决：

方案1：手动下载上传安装

1. 查看本地 VSCode 的版本提交ID（帮助 → 关于，复制 commit id）
2. 到国内镜像站下载对应版本的 vscode-server-linux-x64.tar.gz 安装包
3. 将压缩包上传到服务器 ~/.vscode-server/bin/对应commitID目录 下解压
4. 重启 VSCode 重新连接即可跳过在线下载步骤

方案2：配置远程下载代理

若服务器可配置网络代理，可在服务器环境变量中设置下载代理，或修改 Remote-SSH 插件的下载地址为国内镜像源。

5.4 日常开发实用技巧

1. 集成终端：连接后按 Ctrl+ ` 即可调出服务器终端，无需额外安装终端工具，支持多标签页、分屏操作
2. 文件传输：本地文件可直接拖拽到远程资源管理器的目录中自动上传；远程文件右键可直接下载到本地
3. 插件分离运行：远程服务器可独立安装开发插件（Python、Go、C/C++等），不影响本地插件，代码补全、调试均在服务端执行，准确率更高
4. 端口自动转发：远程服务启动后，VSCode 可自动转发对应端口，本地浏览器直接访问 localhost 即可预览远程服务
5. 防止连接自动断开：在 config 中添加全局配置，自动发送心跳包避免SSH超时断开：

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3

---

六、高频报错与完整解决方案

6.1 连接超时 / 无法建立连接

• 检查服务器公网IP是否输入正确，服务器是否处于正常运行状态
• 确认云服务器安全组、服务器防火墙已放行 SSH 对应端口（默认22）
• 本地终端执行 telnet 服务器IP 22 测试端口连通性，排查本地网络问题
• 服务器 SSH 服务未启动时，登录服务器执行 systemctl start sshd 启动服务

6.2 权限拒绝 / 登录失败

• 核对用户名、密码是否输入正确，注意区分大小写
• 若自定义过 SSH 端口，确认 config 文件中 Port 参数与服务器配置一致
• 服务器禁止 root 用户远程登录：可使用普通用户登录，或修改服务器 /etc/ssh/sshd_config 中的 PermitRootLogin 配置
• 密钥免密失效：检查服务器 .ssh 目录权限为700、authorized_keys 文件权限为600；确认公钥内容完整粘贴，无多余换行或空格

6.3 卡在「正在安装 VS Code 服务器」

• 国内网络拉取官方资源缓慢，参考 5.3 节的手动安装或镜像加速方案
• 检查服务器磁盘空间是否充足，清理根目录冗余文件
• 重启 VSCode 与服务器 SSH 服务后重试

6.4 ssh-keygen 不是内部或外部命令

• 原因：Windows 系统未启用 OpenSSH 客户端
• 解决方案：参考 4.2 节前置步骤，在系统可选功能中安装 OpenSSH 客户端；或安装 Git 后使用 Git Bash 终端执行

6.5 连接后终端中文显示乱码

• 服务器端执行 locale 查看编码，设置为 UTF-8：export LANG=en_US.UTF-8
• 也可在 VSCode 设置中搜索 terminal.integrated.encoding，统一设置为 utf-8

---

七、总结

1. Remote-SSH 是 VSCode 官方原生插件，安全性与兼容性最优，是当前远程开发的首选方案
2. 核心配置集中在 .ssh/config 文件，可统一管理多台、多场景服务器，切换成本极低
3. 密钥免密登录兼顾安全与效率，是生产环境与日常开发的推荐登录方式
4. 国内用户重点关注 vscode-server 下载加速问题，通过手动安装可大幅提升配置成功率
5. 支持跳板机、端口转发等进阶能力，可覆盖个人开发到企业内网的绝大多数场景

配置完成后，即可彻底告别终端+FTP的繁琐工作流，在本地 IDE 中完成全部远程开发与运维工作，大幅提升工作效率。