VSCode 使用 SSH 连接远程服务器全方位教程

Visual Studio Code (VSCode) 凭借其强大的功能、丰富的扩展和友好的用户界面，已成为众多开发者首选的代码编辑器。其中，Remote-SSH 扩展更是将 VSCode 的远程开发体验提升到了一个新的高度。通过 SSH，你可以直接在 VSCode 中连接到远程服务器，像在本地一样进行代码编辑、调试、运行，极大地提高了开发效率，特别是在涉及服务器端开发、大型项目或需要特定运行环境的情况下。

本教程将深入探讨 VSCode Remote-SSH 扩展的使用，从基础配置到高级技巧，涵盖各种场景，力求让你全面掌握这一强大的工具。

一、准备工作：确保本地和服务器端环境就绪

在开始使用 VSCode Remote-SSH 之前，你需要确保本地计算机和远程服务器都已满足以下条件：

1. 本地计算机 (客户端)：

• 安装 Visual Studio Code： 从 VSCode 官网 (https://code.visualstudio.com/) 下载并安装适合你操作系统的 VSCode 版本。
• 安装 Remote-SSH 扩展： 打开 VSCode，进入扩展市场 (快捷键 Ctrl+Shift+X 或 Cmd+Shift+X)，搜索 "Remote - SSH" 并安装。
• 安装 OpenSSH 客户端：
  • Windows: 较新版本的 Windows 10 和 Windows 11 已经内置了 OpenSSH 客户端。你可以通过在 PowerShell 中运行 ssh -V 来检查是否已安装。如果未安装，可以在 "设置" -> "应用" -> "可选功能" 中添加 "OpenSSH 客户端"。
  • macOS: macOS 通常已预装 OpenSSH 客户端。你可以在终端中运行 ssh -V 来检查。
  • Linux: 大多数 Linux 发行版都预装了 OpenSSH 客户端。如果未安装，可以使用你的发行版的包管理器进行安装 (例如，apt install openssh-client (Debian/Ubuntu), yum install openssh-clients (CentOS/RHEL))。
• 生成SSH密钥对（可选但强烈建议）：
  使用密钥对进行身份验证比使用密码更安全、更方便。
  打开终端或PowerShell
  运行ssh-keygen -t rsa -b 4096，一路回车使用默认值即可。
  这会在~/.ssh/目录下生成id_rsa（私钥）和id_rsa.pub（公钥）两个文件。

2. 远程服务器 (服务端)：

• 运行 SSH 服务 (sshd)： 大多数 Linux 服务器默认已安装并运行 SSH 服务。你可以通过 systemctl status sshd (Systemd) 或 service ssh status (SysVinit) 来检查服务状态。如果未运行，请使用你的发行版的包管理器安装并启动 SSH 服务 (例如，apt install openssh-server (Debian/Ubuntu), yum install openssh-server (CentOS/RHEL))。
• 允许 SSH 连接： 确保服务器的防火墙允许 SSH 连接 (通常是端口 22)。
• 用户账户： 你需要一个具有 SSH 登录权限的用户账户。
• 将公钥添加到服务器（如果使用了密钥对）：
  将本地生成的id_rsa.pub（公钥）的内容追加到服务器上目标用户家目录下的~/.ssh/authorized_keys文件中。
  你可以使用ssh-copy-id命令来简化这个过程：ssh-copy-id user@remote_host（将user替换为你的用户名，remote_host替换为服务器地址）。

二、基础连接：快速上手 Remote-SSH

完成准备工作后，我们就可以开始使用 VSCode Remote-SSH 连接到远程服务器了。

1. 打开 Remote Explorer:

点击 VSCode 左侧活动栏中的 Remote Explorer 图标 (或使用快捷键 Ctrl+Shift+P 或 Cmd+Shift+P，输入 "Remote-SSH: Connect to Host...")。

2. 添加 SSH 主机:

• 点击 Remote Explorer 顶部的 "+" 按钮 (或右键点击空白处，选择 "Add New SSH Host...")。
• 输入连接命令：ssh user@remote_host (将 user 替换为你的用户名，remote_host 替换为服务器的 IP 地址或域名)。
• 按回车键。
• 选择一个 SSH 配置文件 (通常选择第一个，即 ~/.ssh/config)。

3. 连接到 SSH 主机:

• 在 Remote Explorer 中，找到你刚刚添加的主机。
• 右键点击主机，选择 "Connect to Host in New Window" (或直接点击主机名旁边的连接图标)。
• 如果使用密码认证，VSCode 会提示你输入密码。如果使用密钥认证，且私钥已正确配置，则会自动连接。
• 首次连接时，VSCode 会在远程服务器上安装 "VSCode Server"，这可能需要一些时间。

4. 开始远程开发:

连接成功后，VSCode 会打开一个新的窗口，状态栏左下角会显示你连接的远程主机。现在，你可以像在本地一样打开远程服务器上的文件夹、编辑文件、使用终端等。

三、进阶配置：定制你的 SSH 连接

虽然基础连接已经可以满足大多数需求，但 Remote-SSH 还提供了许多高级配置选项，可以让你根据自己的需求定制连接。

1. SSH 配置文件 (~/.ssh/config)

SSH 配置文件是管理 SSH 连接的强大工具。通过编辑 ~/.ssh/config 文件 (如果不存在，则创建)，你可以为不同的主机设置不同的选项，简化连接过程。

以下是一些常用的配置选项：

Host my-server # 自定义主机名
HostName 192.168.1.100 # 服务器 IP 地址或域名
User myuser # 用户名
Port 2222 # SSH 端口 (如果不是默认的 22 端口)
IdentityFile ~/.ssh/my_server_key # 指定私钥文件
ForwardAgent yes #开启ssh 密钥代理
ServerAliveInterval 60 #设置每60s发送一次请求给server，保持连接
Host github.com # 针对特定域名的配置
User git
Hostname ssh.github.com
Port 443
IdentityFile ~/.ssh/id_rsa_github

配置说明:

• Host: 定义一个主机别名，方便后续使用。
• HostName: 服务器的 IP 地址或域名。
• User: 登录用户名。
• Port: SSH 端口 (如果不是默认的 22 端口)。
• IdentityFile: 指定用于身份验证的私钥文件。
• ForwardAgent: 启用 SSH agent forwarding, 允许你在远程服务器上使用本地的 SSH 密钥, 从而访问其他需要密钥认证的资源 (例如 Git 仓库)。
• ServerAliveInterval: 设置一个时间间隔 (秒), VSCode 会定期向服务器发送 keep-alive 消息, 防止连接因长时间空闲而断开。

配置完成后，你可以直接使用 ssh my-server (假设你定义了 Host my-server) 来连接到服务器，而无需输入完整的连接命令。在 VSCode Remote Explorer 中，也会显示你配置的主机别名。

2. Remote-SSH 扩展设置

在 VSCode 中，你可以通过 "文件" -> "首选项" -> "设置" (或快捷键 Ctrl+, 或 Cmd+,)，搜索 "Remote-SSH"，找到 Remote-SSH 扩展的设置。

以下是一些常用的设置选项：

• remote.SSH.configFile: 指定 SSH 配置文件的路径 (默认为 ~/.ssh/config)。
• remote.SSH.showLoginTerminal: 在连接过程中显示 SSH 登录终端 (默认为 false)。
• remote.SSH.path: 指定本地 SSH 可执行文件的路径 (如果系统中有多个 SSH 版本，或 SSH 不在默认路径下，可能需要设置)。
• remote.SSH.useLocalServer: 在本地启动 VSCode Server, 而不是在远程服务器上 (实验性功能)。
• remote.SSH.remotePlatform：手动指定远程服务器的操作系统，这可以帮助 VSCode Server 选择正确的版本。

3. 多因素身份验证 (MFA)

如果你的服务器启用了多因素身份验证 (例如 Google Authenticator、Duo Mobile 等)，Remote-SSH 也能很好地支持。

通常，你需要在 SSH 配置文件中添加 KbdInteractiveAuthentication yes 选项：

Host my-server
HostName 192.168.1.100
User myuser
KbdInteractiveAuthentication yes

连接时，VSCode 会提示你输入验证码 (通常是在终端中)。

4. 通过跳板机 (Jump Host) 连接

在某些情况下，你可能需要通过一个或多个跳板机 (也称为堡垒机) 才能访问目标服务器。Remote-SSH 也支持这种场景。

你可以在 SSH 配置文件中使用 ProxyJump 选项来配置跳板机：

```
Host target-server
HostName target.example.com
User myuser
ProxyJump jump-host

Host jump-host
HostName jump.example.com
User jumpuser
你也可以使用ProxyCommand
Host target-server
HostName target.example.com
User myuser
ProxyCommand ssh -W %h:%p jump-host
Host jump-host
HostName jump.example.com
User jumpuser
```

这样，当你连接到 target-server 时，SSH 会先连接到 jump-host，然后再通过 jump-host 连接到 target-server。

如果需要通过多个跳板机连接，可以使用逗号分隔多个主机名：

ProxyJump jump1,jump2,jump3

5.端口转发

SSH 端口转发允许你将远程服务器上的端口映射到本地计算机，或者将本地计算机的端口映射到远程服务器。这在访问远程服务器上的服务 (例如 Web 应用、数据库等) 时非常有用。

• 本地端口转发 (Local Forwarding): 将远程服务器上的端口映射到本地计算机。

  在 SSH 配置文件中添加 LocalForward 选项：

  Host my-server
HostName 192.168.1.100
User myuser
LocalForward localhost:8080 remote-server:80

  这表示将远程服务器 remote-server 上的 80 端口映射到本地计算机的 8080 端口。连接后，你可以在本地浏览器中访问 localhost:8080 来访问远程服务器上的 Web 应用。

• 远程端口转发 (Remote Forwarding): 将本地计算机的端口映射到远程服务器。

  在 SSH 配置文件中添加 RemoteForward 选项：

  Host my-server
HostName 192.168.1.100
User myuser
RemoteForward remote-server:3306 localhost:3306

  这表示将本地计算机的 3306 端口 (例如 MySQL 数据库) 映射到远程服务器 remote-server 的 3306 端口。连接后，远程服务器上的应用可以通过 remote-server:3306 来访问本地计算机上的数据库。

四、常见问题及解决方案

在使用 VSCode Remote-SSH 的过程中，你可能会遇到一些问题。以下是一些常见问题及其解决方案：

1. 连接超时:

• 检查网络连接： 确保你的本地计算机可以访问远程服务器。
• 检查 SSH 服务： 确保远程服务器上的 SSH 服务正在运行，并且防火墙允许 SSH 连接。
• 增加超时时间： 在 SSH 配置文件中添加 ConnectTimeout 选项，增加连接超时时间 (单位为秒)。

2. 身份验证失败:

• 检查用户名和密码： 确保你输入的用户名和密码正确。
• 检查密钥： 如果使用密钥认证，确保你的私钥文件路径正确，并且公钥已添加到远程服务器的 ~/.ssh/authorized_keys 文件中。
• 检查权限： 确保 ~/.ssh 目录和 authorized_keys 文件的权限设置正确 (通常 ~/.ssh 权限为 700，authorized_keys 权限为 600)。

3. VSCode Server 安装失败:

• 检查网络连接： 确保远程服务器可以访问互联网 (VSCode Server 需要从网络下载)。
• 手动安装： 你可以尝试手动下载 VSCode Server 并上传到远程服务器。具体步骤可以参考 VSCode 官方文档。
• 指定平台 尝试在setting里面配置remote.SSH.remotePlatform

4. 连接断开:

• 检查网络连接： 网络不稳定可能导致连接断开。
• 启用 keep-alive： 在 SSH 配置文件中添加 ServerAliveInterval 选项，定期发送 keep-alive 消息，防止连接因长时间空闲而断开。

5. 终端无法使用:

• 检查 Shell： 确保远程服务器上安装了你选择的 Shell (例如 bash、zsh 等)。
• 设置默认 Shell： 在 VSCode 设置中搜索 "terminal.integrated.shell.linux" (或相应的操作系统)，设置你希望使用的 Shell。

6. 无法访问远程服务器上的某些文件或目录:

• 检查权限： 确保你使用的用户账户对这些文件或目录具有访问权限。

7.性能问题
* 减少远程加载的扩展，只启用必要的。
* 对于大型项目，考虑使用更快的网络连接。

五、总结

VSCode Remote-SSH 扩展是一个强大而灵活的工具，可以极大地提升远程开发的效率和体验。通过本教程，你应该已经掌握了 Remote-SSH 的基本使用方法和各种高级配置选项。希望你能充分利用这一工具，让远程开发变得更加轻松愉快！

请记住，熟练掌握 SSH 本身的知识 (例如密钥管理、配置文件、端口转发等) 对于充分利用 Remote-SSH 扩展至关重要。建议你花一些时间学习 SSH 的相关知识，这将使你在使用 Remote-SSH 时更加得心应手。