vscode如何连接远程服务器 – 完整指南

VSCode连接远程服务器主要通过其官方的Remote – SSH 扩展实现。这个扩展允许您通过安全外壳协议（SSH）连接到任何远程计算机，并在其上无缝地编辑文件、运行终端命令以及调试应用程序，就像在本地工作一样。

连接步骤概括为：

  1. 在VSCode中安装Remote – SSH 扩展。
  2. 配置您的SSH连接信息（通常在~/.ssh/config文件中或直接通过VSCode界面）。
  3. 通过VSCode命令面板选择远程主机进行连接，并输入密码或使用SSH密钥进行身份验证。

什么是VSCode远程开发？为什么选择它？

VSCode远程开发是一种强大的功能，它允许您将VSCode的用户界面（UI）运行在本地电脑上，而实际的代码编辑、编译、调试等操作都在一个远程的服务器（如云虚拟机、物理服务器、WSL或Docker容器）上执行。

选择VSCode远程开发的优势：

  • 一致的开发环境： 确保团队成员在统一的服务器环境中工作，避免“在我的机器上能跑”的问题。
  • 强大的服务器资源： 利用远程服务器的强大CPU、GPU和内存资源进行编译、测试和运行大型应用，同时享受本地VSCode的流畅体验。
  • 代码安全： 源代码可以安全地保留在远程服务器上，本地设备只传输显示信息。
  • 跨平台无缝体验： 无论您的本地机器是Windows、macOS还是Linux，都能连接到远程的Linux服务器进行开发。
  • 节省本地资源： 避免在本地安装大量开发工具和依赖，保持本地环境的整洁。

连接远程服务器的先决条件

在开始连接之前，请确保满足以下条件：

  • 本地已安装VSCode： 您的本地计算机上必须安装有最新版本的Visual Studio Code。
  • 本地SSH客户端：

    • Windows： 推荐使用WSL (Windows Subsystem for Linux) 中的OpenSSH客户端，或者安装Git for Windows（它通常包含OpenSSH）。您也可以安装原生的OpenSSH客户端。
    • macOS/Linux： 通常预装了OpenSSH客户端，无需额外安装。
  • 远程服务器运行SSH服务： 目标远程服务器必须开启并运行SSH服务（sshd），且允许通过SSH进行连接。通常Linux服务器默认已安装并开启。
  • SSH凭据：

    • 用户名和密码： 远程服务器的有效用户名和密码。
    • SSH密钥对： 更安全且推荐的方式。您需要有一个本地私钥（例如~/.ssh/id_rsa）和一个远程服务器上的公钥（位于~/.ssh/authorized_keys文件内）。

核心步骤：使用Remote – SSH扩展连接

步骤一：安装Remote – SSH扩展

这是连接远程服务器的第一步，也是最关键的一步。

  1. 打开您的本地VSCode。
  2. 点击左侧活动栏中的“扩展”图标（通常是四个方块组成的正方形）。
  3. 在搜索框中输入“Remote – SSH”。
  4. 找到由“Microsoft”发布的“Remote – SSH”扩展，点击“安装”按钮。

安装成功后，VSCode的左下角会出现一个新的绿色图标（或在状态栏显示一个“打开远程”的按钮）。

步骤二：配置SSH连接

您可以通过两种主要方式配置SSH连接信息：

方式一：直接通过VSCode界面添加主机

这种方式简单快捷，适合初次连接或连接较少的主机。

  1. 在VSCode中，按下快捷键 Ctrl+Shift+P （macOS上是 Cmd+Shift+P ）打开命令面板。
  2. 输入“Remote-SSH: Connect to Host”，然后选择该命令。
  3. 选择“Add New SSH Host…”。
  4. 在弹出的输入框中，输入您的SSH连接字符串。格式通常为 user@hostname 或 user@IP_address。

    例如：your_username@your_server_ip 或 your_username@your_domain.com

    如果您的SSH端口不是默认的22，则需要指定端口：ssh -p PortNumber user@hostname

    例如：ssh -p 2222 your_username@your_server_ip
  5. VSCode会询问您要将此配置保存到哪个SSH配置文件。选择默认的 ~/.ssh/config 文件即可。

成功添加后，该主机就会出现在“Remote-SSH: Connect to Host”的列表中。

方式二：手动编辑SSH配置文件 (~/.ssh/config)

对于需要管理多个远程主机、使用SSH密钥、端口转发或其他高级SSH配置的用户，直接编辑SSH配置文件 ~/.ssh/config 是更推荐且强大的方式。

  1. 在VSCode中，按下 Ctrl+Shift+P （macOS上是 Cmd+Shift+P ），输入“Remote-SSH: Open SSH Configuration File…”，然后选择您希望编辑的配置文件。通常是默认的 ~/.ssh/config。
  2. 该文件会以新标签页的形式打开。您可以按照以下格式添加或修改主机配置：

    Host MyRemoteServer
        HostName your_server_ip_or_domain
        User your_username
        Port 22
        IdentityFile ~/.ssh/id_rsa

    • Host： 给这个连接起一个易于识别的别名（例如 MyRemoteServer）。这是您在VSCode中看到的名称。
    • HostName： 远程服务器的实际IP地址或域名。
    • User： 连接远程服务器时使用的用户名。
    • Port： 远程服务器SSH服务的端口号，默认为22。如果您的服务器使用非标准端口，请在此处指定。
    • IdentityFile： （可选）指定用于身份验证的SSH私钥文件的路径。如果您使用SSH密钥连接，这是必需的。
  3. 保存 ~/.ssh/config 文件。

步骤三：建立远程连接

配置完成后，即可进行连接。

  1. 点击VSCode左下角的绿色远程指示器图标，或者再次按下 Ctrl+Shift+P （macOS上是 Cmd+Shift+P ）并输入“Remote-SSH: Connect to Host”。
  2. 在列表中选择您之前配置好的远程主机（例如“MyRemoteServer”或 user@IP_address）。
  3. VSCode将尝试通过SSH连接到远程服务器。

    • 如果是首次连接： 可能会提示您确认主机的指纹。输入“yes”并按回车继续。
    • 如果使用密码： VSCode会在顶部弹出一个输入框，要求您输入远程用户的密码。
    • 如果使用SSH密钥： 如果您的私钥有密码（passphrase），则会提示您输入。如果没有，通常会直接连接。
  4. 连接成功后，一个新的VSCode窗口将打开。此窗口现在已连接到远程服务器。您可以点击“Open Folder”按钮（或通过 Ctrl+Shift+P -> “Remote-SSH: Open Folder…”）选择远程服务器上的一个工作目录。

此时，您会发现VSCode左下角的绿色指示器会显示您已连接到远程主机的信息。

远程开发中的常用操作与技巧

集成终端

连接到远程服务器后，您可以直接在VSCode中打开集成终端（ Ctrl+` ）。这个终端运行在远程服务器上，您可以像在服务器本地一样执行任何命令。

文件管理

在资源管理器视图中（左侧第一个图标），您可以浏览、创建、编辑、删除远程服务器上的文件和文件夹。就像操作本地文件一样。

扩展安装

当连接到远程服务器时，VSCode会提示您安装某些扩展到远程服务器上。例如，Python扩展、Docker扩展等，它们需要在远程环境中运行才能发挥作用。您在本地安装的UI相关的扩展（如主题、图标包）会自动同步。

端口转发

如果您在远程服务器上运行了一个Web服务或数据库，并且希望在本地浏览器或客户端访问它，可以使用VSCode的端口转发功能。

  1. 点击VSCode左下角的绿色远程指示器图标。
  2. 选择“端口转发”选项卡。
  3. 点击“添加端口”，输入远程服务器上正在监听的端口号（例如8000），然后选择一个本地端口（通常会自动分配）。

这样，您就可以通过本地的 http://localhost:本地端口 来访问远程服务器上的服务。

断开连接

要断开与远程服务器的连接，您可以直接关闭当前VSCode窗口。
或者，在VSCode中，按下 Ctrl+Shift+P （macOS上是 Cmd+Shift+P ），然后输入“Remote-SSH: Disconnect from Host”并选择该命令。

常见问题与故障排除

“Permission denied (publickey, password).” 或 无法连接

  • SSH密钥问题： 确保您的本地私钥权限正确（通常是 chmod 600 ~/.ssh/id_rsa），且公钥已正确添加到远程服务器用户的 ~/.ssh/authorized_keys 文件中。
  • 密码错误： 仔细检查您输入的密码。
  • 用户名错误： 确保您使用的是远程服务器上的有效用户名。
  • SSH Agent： 如果您使用SSH密钥并多次输入密码，考虑使用 ssh-agent 来管理您的密钥。

“Could not establish connection. Check your network connection.” 或 “Connection timed out.”

  • 网络连接： 检查您的本地网络连接，并确保远程服务器可从您的网络访问。
  • IP地址或域名： 确认您输入的IP地址或域名是正确的。
  • 防火墙： 检查远程服务器的防火墙（如ufw、firewalld）是否阻止了SSH端口（默认为22）。同时检查本地防火墙。
  • SSH服务未运行： 确保远程服务器上的SSH服务（sshd）正在运行。在Linux上，可以使用 sudo systemctl status sshd 或 sudo service ssh status 命令查看。
  • 端口号： 如果SSH服务运行在非标准端口，请确保在 ~/.ssh/config 或连接字符串中指定了正确的端口。

“VSCode Server failed to start”

  • 远程服务器磁盘空间不足： VSCode会在远程服务器上安装一个小型服务（VSCode Server）。如果远程服务器的 /tmp 目录或用户主目录磁盘空间不足，服务可能无法启动。
  • 权限问题： 确保远程用户对主目录有写入权限。
  • 依赖缺失： 某些情况下，远程服务器可能缺少VSCode Server运行所需的依赖库。VSCode通常会提示您安装。
  • 手动清除VSCode Server： 在远程服务器上，您可以尝试删除 ~/.vscode-server 目录，然后重新连接，让VSCode重新安装服务。

~/.ssh/config 文件语法错误

一个小的缩进或拼写错误都可能导致配置文件失效。请仔细检查文件内容，确保格式正确。使用 ssh -vvv your_host_alias 命令可以在终端中进行详细的SSH连接诊断，帮助排查问题。

通过遵循本指南，您应该能够顺利地使用VSCode连接到您的远程服务器，并享受高效、无缝的远程开发体验。

vscode如何连接远程服务器