VSCode Remote SSH 使用教程：从安装到实战操作 – wiki基地

作者： /

VSCode Remote SSH：连接远程服务器开发的终极指南（从安装到实战）

在现代软件开发中，我们经常需要在远程服务器上进行开发、调试和部署。传统的开发方式，如通过FTP/SFTP同步代码、使用SSH终端登录后编辑，效率低下且容易出错。VSCode Remote SSH 插件的出现，彻底改变了这一现状。它允许你像在本地一样无缝地在远程服务器上进行开发，享受本地VSCode的强大功能和舒适体验。

本文将深入探讨VSCode Remote SSH插件，从安装配置到高级特性，提供一个全面、详细的使用指南，帮助你充分利用这个强大的工具，提高开发效率。

一、为什么选择 VSCode Remote SSH？

在深入了解如何使用VSCode Remote SSH之前，让我们先看看它为什么如此受欢迎，以及它能为你带来哪些好处：

  • 无缝的本地开发体验： Remote SSH 将远程服务器的文件系统和环境映射到本地VSCode中，你可以像编辑本地文件一样编辑远程文件，无需手动同步代码。
  • 本地化的开发工具： 你可以在远程服务器上使用本地VSCode的所有功能，包括智能提示、代码补全、调试器、Git集成、扩展插件等，无需在远程服务器上安装和配置复杂的开发环境。
  • 隔离的开发环境： 每个远程连接都在一个独立的容器化环境中运行，避免了不同项目之间的环境冲突，也保证了本地机器的清洁。
  • 安全性： Remote SSH 使用安全的 SSH 协议进行连接，保障数据传输的安全性。
  • 跨平台支持： VSCode 和 Remote SSH 插件都支持 Windows、macOS 和 Linux，你可以轻松地在不同的操作系统之间切换。
  • 性能优化： VSCode Remote SSH 对性能进行了优化，即使在网络条件不佳的情况下也能提供流畅的开发体验。

二、安装与配置：迈出第一步

在使用 Remote SSH 之前，你需要进行一些简单的安装和配置。

1. 安装 VSCode：

如果你还没有安装 VSCode，请访问 VSCode 官网（https://code.visualstudio.com/）下载并安装适合你操作系统的版本。

2. 安装 Remote – SSH 扩展：

打开 VSCode，点击左侧边栏的扩展图标（或按下快捷键 Ctrl+Shift+X / Cmd+Shift+X），搜索 “Remote – SSH”，找到由 Microsoft 发布的官方扩展，点击 “Install” 进行安装。

3. 确保本地和远程服务器已安装 SSH：

  • 本地机器：

    • Windows: Windows 10 和 Windows 11 通常已内置 OpenSSH 客户端，你可以通过在 PowerShell 或命令提示符中输入 ssh -V 来检查是否已安装。如果没有安装，可以通过 “设置” -> “应用” -> “可选功能” -> “添加功能” 来安装 “OpenSSH 客户端”。
    • macOS 和 Linux: 通常已预装 SSH 客户端，你可以通过在终端中输入 ssh -V 来检查。

  • 远程服务器：

    • 大多数 Linux 发行版都预装了 OpenSSH 服务器。你可以通过 ssh -V 或 sshd -v来检查版本,以及systemctl status sshd来查看ssh服务状态。如果没有安装，可以使用包管理器（如 apt、yum、dnf 等）进行安装。例如，在 Ubuntu/Debian 上，可以使用 sudo apt update && sudo apt install openssh-server 进行安装。

4. SSH 密钥配置（推荐）：

虽然你可以使用密码进行 SSH 连接，但强烈建议使用 SSH 密钥进行身份验证，因为它更安全、更方便。

  • 生成 SSH 密钥对：

    • 打开终端或 PowerShell，运行以下命令：
      bash
      ssh-keygen -t rsa -b 4096 -C "[email protected]"
      这将生成一个 RSA 密钥对，-b 4096 指定密钥长度为 4096 位（更安全），-C 选项用于添加注释（通常是你的邮箱地址）。
      系统会提示你输入密钥文件的保存路径（默认为 ~/.ssh/id_rsa）和密码（可选，用于保护私钥）。
    • 生成后，你会在 ~/.ssh/ 目录下找到两个文件：id_rsa（私钥，务必妥善保管）和 id_rsa.pub（公钥）。

  • 将公钥复制到远程服务器：

    • 你可以使用 ssh-copy-id 命令（如果可用）将公钥复制到远程服务器：
      bash
      ssh-copy-id user@remote_host
      其中 user 是你在远程服务器上的用户名，remote_host 是远程服务器的 IP 地址或域名。
    • 如果没有 ssh-copy-id 命令，你可以手动复制公钥内容并将其添加到远程服务器的 ~/.ssh/authorized_keys 文件中：
      1. 在本地机器上，复制公钥内容：
        bash
        cat ~/.ssh/id_rsa.pub
      2. 使用 SSH 连接到远程服务器：
        bash
        ssh user@remote_host
      3. 在远程服务器上，编辑 ~/.ssh/authorized_keys 文件（如果不存在则创建）：
        bash
        mkdir -p ~/.ssh
        nano ~/.ssh/authorized_keys
      4. 将本地复制的公钥内容粘贴到 authorized_keys 文件中，保存并关闭文件。
      5. 设置 authorized_keys 文件的权限：
        bash
        chmod 600 ~/.ssh/authorized_keys
        chmod 700 ~/.ssh

三、连接到远程服务器：开始远程开发

配置完成后，就可以开始使用 Remote SSH 连接到远程服务器了。

1. 通过命令面板连接：

  • 按下 Ctrl+Shift+P / Cmd+Shift+P 打开命令面板。
  • 输入 “Remote-SSH: Connect to Host…” 并选择该命令。
  • VSCode 会读取你的 SSH 配置文件（通常位于 ~/.ssh/config），列出已配置的 SSH 主机。如果没有，你可以选择 “+ Add New SSH Host…”。
  • 选择你要连接的主机，或输入 user@remote_host 格式的连接信息。
  • 如果需要，输入密码（如果未使用密钥认证）。
  • VSCode 将连接到远程服务器，并在新窗口中打开远程工作区。

2. 通过 SSH 配置文件连接：

如果你经常连接到相同的远程服务器，可以将连接信息添加到 SSH 配置文件中，以便更方便地连接。

  • 打开 SSH 配置文件（通常位于 ~/.ssh/config）：
    bash
    nano ~/.ssh/config

  • 添加以下配置块（根据你的实际情况修改）：
    Host my-remote-server
    HostName remote_host_ip_or_domain
    User your_username
    IdentityFile ~/.ssh/id_rsa
    # 可选的其他配置
    # Port 2222 # 如果 SSH 端口不是默认的 22
    # ForwardAgent yes # 如果需要 SSH 代理转发

    • Host: 自定义的别名，方便你在 VSCode 中识别。
    • HostName: 远程服务器的 IP 地址或域名。
    • User: 你在远程服务器上的用户名。
    • IdentityFile: 私钥文件的路径。

  • 保存并关闭配置文件。

  • 现在，你可以通过命令面板或左下角的 Remote Explorer 连接到 my-remote-server。

3. 通过 Remote Explorer 连接：

  • 点击 VSCode 左侧活动栏的 Remote Explorer 图标（看起来像一个插头）。
  • 在 “SSH Targets” 下，你会看到已配置的 SSH 主机。
  • 点击你要连接的主机旁边的 “+” 图标，或右键点击主机并选择 “Connect to Host in New Window”。

四、远程开发：享受本地般的体验

连接到远程服务器后，你就可以像在本地一样进行开发了。

  • 打开远程文件夹：

    • 点击 “File” -> “Open Folder…”，选择远程服务器上的文件夹。
    • 或者，在命令面板中输入 “File: Open Folder…” 并选择远程文件夹。

  • 编辑文件：

    • 像编辑本地文件一样编辑远程文件。VSCode 会自动处理文件的保存和同步。

  • 使用终端：

    • VSCode 的集成终端会自动连接到远程服务器。你可以在终端中运行命令、安装软件包、启动服务等。

  • 使用调试器：

    • VSCode 的调试器可以在远程服务器上运行。你可以设置断点、单步执行代码、查看变量值等。

  • 使用扩展插件：

    • 大多数 VSCode 扩展插件都可以在远程环境中工作。你可以在远程环境中安装和使用它们。

  • Git 集成：

    • VSCode 的 Git 集成可以在远程服务器上工作。你可以进行代码提交、拉取、推送等操作。

五、高级特性：更强大的功能

Remote SSH 还提供了一些高级特性，可以进一步提升你的开发体验。

1. 端口转发：

端口转发允许你将远程服务器上的端口映射到本地机器，以便你可以通过本地浏览器访问远程服务器上的 Web 应用或服务。

  • 在 SSH 配置文件中配置端口转发：
    Host my-remote-server
    HostName remote_host_ip_or_domain
    User your_username
    IdentityFile ~/.ssh/id_rsa
    LocalForward localhost:8080 remote_host:80 # 将远程服务器的 80 端口映射到本地的 8080 端口
  • 在 VSCode 中配置端口转发：
    1. 连接到远程服务器。
    2. 点击 VSCode 状态栏中的端口号（如果已配置端口转发，会显示端口号）。
    3. 点击 “+” 图标添加新的端口转发规则。
    4. 输入远程端口和本地端口。

2. SSH 代理转发：

如果你需要从远程服务器访问其他需要 SSH 密钥认证的服务器（例如，从开发服务器访问 Git 仓库），可以使用 SSH 代理转发。

  • 在 SSH 配置文件中配置代理转发：
    Host my-remote-server
    HostName remote_host_ip_or_domain
    User your_username
    IdentityFile ~/.ssh/id_rsa
    ForwardAgent yes
  • 在本地机器上启动 SSH 代理：
    bash
    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa

3. 多工作区：

你可以在同一个 VSCode 窗口中打开多个远程文件夹，方便你在多个项目之间切换。

  • 点击 “File” -> “Add Folder to Workspace…”，选择远程文件夹。

4. Remote – SSH: Editing Configuration Files 扩展：

这个扩展可以帮助你更方便地编辑 SSH 配置文件。安装后，你可以通过命令面板或 Remote Explorer 编辑 SSH 配置文件。

5. Remote Development 扩展包：
Remote Development扩展包包含了Remote-SSH, Remote-Containers, Remote-WSL这三个插件,可以提供更加全面的远程开发体验。

六、常见问题与解决方案

  • 连接失败：

    • 检查网络连接是否正常。
    • 检查 SSH 服务是否在远程服务器上运行。
    • 检查用户名、密码或密钥是否正确。
    • 检查防火墙设置是否允许 SSH 连接。

  • 扩展插件无法安装或运行：

    • 确保远程服务器已安装扩展插件所需的依赖项。
    • 尝试重新安装扩展插件。
    • 检查扩展插件的文档，了解是否需要特殊的配置。

  • 性能问题：

    • 优化网络连接
    • 减少需要同步的文件数量(使用.gitignore或.vscodeignore)
    • 升级VSCode和Remote-SSH插件到最新版本

  • 无法打开远程文件夹：

    • 检查你是否具有访问远程文件夹的权限。
    • 检查远程服务器上的文件系统是否支持VSCode(例如某些特殊的文件系统可能不兼容)

七、实战案例：远程开发一个 Node.js 项目

让我们通过一个实际的案例来演示如何使用 Remote SSH 远程开发一个 Node.js 项目。

  1. 准备远程服务器：

    • 确保远程服务器已安装 Node.js 和 npm。
    • 创建一个用于存放项目的文件夹，例如 ~/my-node-app。

  2. 连接到远程服务器：

    • 使用 VSCode Remote SSH 连接到远程服务器。

  3. 打开远程文件夹：

    • 在 VSCode 中打开 ~/my-node-app 文件夹。

  4. 创建项目：

    • 在 VSCode 的集成终端中，运行以下命令：
      bash
      npm init -y
      npm install express

  5. 创建 app.js 文件：
    “`javascript
    const express = require(‘express’);
    const app = express();

    app.get(‘/’, (req, res) => {
    res.send(‘Hello from Remote Server!’);
    });

    const port = 3000;
    app.listen(port, () => {
    console.log(Server listening on port ${port});
    });
    “`

  6. 运行项目：

    • 在 VSCode 的集成终端中，运行 node app.js。

  7. 配置端口转发：

    • 将远程服务器的 3000 端口映射到本地的 3000 端口。

  8. 在本地浏览器中访问：

    • 打开浏览器，访问 http://localhost:3000，你应该能看到 “Hello from Remote Server!”。

  9. 调试项目：

    • 在app.js中设置断点
    • 在VSCode调试面板,选择”创建一个launch.json文件”, 选择Node.js环境
    • 点击启动调试按钮, 即可像本地调试一样进行远程调试

八、总结

VSCode Remote SSH 是一款强大的工具，它可以极大地提高远程开发的效率和体验。通过本文的详细介绍，你应该已经掌握了 Remote SSH 的安装、配置和使用方法。现在，你可以开始享受无缝的远程开发体验了！

希望本文对你有所帮助！如果你有任何问题或建议，请随时提出。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部