现已推出！阅读有关 11 月份的新功能和修复的信息。

使用 SSH 进行远程开发

Visual Studio Code Remote - SSH 扩展允许您在任何具有正在运行的 SSH 服务器的远程计算机、虚拟机或容器上打开远程文件夹，并充分利用 VS Code 的功能集。连接到服务器后，您可以与远程文件系统上的任何位置的文件和文件夹进行交互。

无需将源代码放在本地计算机上即可获得这些好处，因为该扩展程序直接在远程计算机上运行命令和其他扩展程序。

SSH Architecture

这使 VS Code 能够提供本地质量的开发体验- 包括完整的 IntelliSense（补全）、代码导航和调试 - 无论您的代码托管在何处。

入门

注意：阅读完本主题后，您可以开始学习入门级 SSH 教程。

系统要求

本地：还必须安装受支持的 OpenSSH 兼容 SSH 客户端。

远程 SSH 主机：在以下位置运行的 SSH 服务器：

  • x86_64 Debian 8+、Ubuntu 16.04+、CentOS/RHEL 7+。
  • ARMv7l (AArch32) Raspberry Pi OS（以前称为 Raspbian）Stretch/9+（32 位）。
  • ARMv8l (AArch64) Ubuntu 18.04+（64 位）。
  • 使用官方 OpenSSH 服务器的 Windows 10/服务器 2016/2019 (1803+)。
  • macOS 10.14+ (Mojave) 已启用 远程登录的 SSH 主机。
  • 远程主机需要 1 GB RAM，但建议至少 2 GB RAM 和 2 核 CPU。

如果其他基于 glibc 的 x86_64、ARMv7l (AArch32) 和 ARMv8l (AArch64) Linux 发行版具有所需的前提条件，则应该可以使用。有关前提条件以及启动和运行社区支持的发行版的提示，请参阅 使用 Linux 进行远程开发文章。

虽然 ARMv7l (AArch32) 和 ARMv8l (AArch64) 支持可用，但由于扩展程序中使用了 x86 本机代码，因此安装在这些设备上的某些扩展程序可能无法工作。

安装

要开始使用，您需要

  1. 安装 OpenSSH 兼容 SSH 客户端（如果尚未安装）。

  2. 安装 Visual Studio Code 或 Visual Studio Code Insiders。

  3. 安装 Remote-SSH 扩展。如果您计划在 VS Code 中使用其他远程扩展，您可以选择安装 远程开发扩展包。

SSH 主机设置

  1. 如果您没有设置 SSH 主机，请按照Linux、Windows 10/服务器 (1803+) 或 macOS SSH 主机的说明进行操作，或者在 Azure 上创建 VM。

  2. 可选：如果多个用户将同时访问您的 Linux 或 macOS SSH 主机，请考虑在 VS Code 用户设置中启用Remote.SSH: Remote Server Listen On Socket，以提高安全性。

    在设置编辑器中

    Listen on socket VS Code setting

    有关详细信息，请参阅技巧和窍门文章。

  3. 可选：虽然支持基于密码的身份验证，但我们建议为您的主机设置基于密钥的身份验证。有关详细信息，请参阅技巧和窍门文章。

连接到远程主机

要首次连接到远程主机，请执行以下步骤

  1. 通过从终端/PowerShell 窗口运行以下命令（并根据需要替换 user@hostname）来验证您是否可以连接到 SSH 主机。

    ssh user@hostname
# Or for Windows when using a domain / AAD account
ssh user@domain@hostname

  2. 在 VS Code 中，从命令面板中选择远程-SSH：连接到主机...（F1，⇧⌘P (Windows、Linux Ctrl+Shift+P))，并使用与步骤 1 中相同的 user@hostname。

    Illustration of user@host input box

  3. 如果 VS Code 无法自动检测您要连接的服务器类型，系统会要求您手动选择类型。

    Illustration of platform selection

    选择平台后，它将存储在 VS Code 设置的 remote.SSH.remotePlatform 属性下，因此您可以随时更改它。

  4. 片刻之后，VS Code 将连接到 SSH 服务器并自行设置。VS Code 将使用进度通知让您保持最新状态，您可以在 Remote - SSH 输出通道中看到详细的日志。

    提示：连接挂起或失败？有关解决常见问题的信息，请参阅故障排除提示。

    如果您看到有关 SSH 文件权限的错误，请参阅有关修复 SSH 文件权限错误的部分。

  5. 连接后，您将进入一个空窗口。您可以随时参考状态栏以查看您连接到哪个主机。

    SSH Status bar item

    单击状态栏项目将在您连接时提供远程命令列表。

  6. 然后，您可以使用文件 > 打开...或文件 > 打开工作区...在远程计算机上打开任何文件夹或工作区，就像在本地一样！

    File Open on a remote SSH host

从这里，安装您在连接到主机时要使用的任何扩展，然后开始编辑！

注意：在 ARMv7l/ARMv8l glibc SSH 主机上，由于扩展程序内部包含 x86 编译的本机代码，因此某些扩展程序可能无法工作。

在容器中打开远程 SSH 主机上的文件夹

如果您使用的是 Linux 或 macOS SSH 主机，您可以一起使用 Remote - SSH 和开发容器扩展，以在容器内打开远程主机上的文件夹。您甚至不需要在本地安装 Docker 客户端。

要执行此操作

  1. 按照安装步骤在您的远程主机和 VS Code 上安装 Docker，并在本地安装开发容器扩展。
  2. 可选：设置到服务器的 SSH 密钥身份验证，这样您就不需要多次输入密码。
  3. 按照 Remote - SSH 扩展的快速入门连接到主机并在那里打开一个文件夹。
  4. 从命令面板中使用 Dev Containers: Reopen in Container 命令（F1，⇧⌘P（Windows，Linux Ctrl+Shift+P））。

Dev Containers 快速入门的其余部分按原样适用。您可以在其文档中了解有关 Dev Containers 扩展的更多信息。如果此模型不符合您的需求，您还可以查看在远程 Docker 主机上开发文章以获取其他选项。

断开与远程主机的连接

要在完成远程主机上的文件编辑后关闭连接，请选择文件 > 关闭远程连接以断开与主机的连接。默认配置不包含此命令的键盘快捷键。您也可以简单地退出 VS Code 来关闭远程连接。

记住主机和高级设置

如果您有一组经常使用的主机，或者您需要使用一些附加选项连接到主机，您可以将它们添加到一个遵循SSH 配置文件格式的本地文件中。

为了方便设置，该扩展可以指导您添加主机，而无需手动编辑此文件。

首先从命令面板中选择 Remote-SSH: Add New SSH Host...（F1，⇧⌘P（Windows，Linux Ctrl+Shift+P））或单击活动栏中 SSH 远程资源管理器中的 Add New 图标。

Remote Explorer Add New item

然后，系统会要求您输入 SSH 连接信息。您可以输入主机名

Remote Explorer SSH host input

或您将用于从命令行连接到主机的完整 ssh 命令

Remote Explorer SSH command input

最后，系统会要求您选择要使用的配置文件。如果您想使用与列表中不同的配置文件，也可以在用户 settings.json 文件中设置 "remote.SSH.configFile" 属性。该扩展会处理其余的事情！

例如，在输入框中输入 ssh -i ~/.ssh/id_rsa-remote-ssh [email protected] 将生成此条目

Host remotehost.yourcompany.com
    User yourname
    HostName another-host-fqdn-or-ip-goes-here
    IdentityFile ~/.ssh/id_rsa-remote-ssh

有关生成此处显示的密钥的详细信息，请参阅提示和技巧。您可以使用 SSH 配置文件格式 支持的任何内容手动编辑此文件，所以这只是一个示例。

从现在开始，当您从命令面板中选择 Remote-SSH: Connect to Host...（F1，⇧⌘P（Windows，Linux Ctrl+Shift+P））或在 远程资源管理器的 SSH 目标部分中时，该主机将出现在主机列表中。

SSH targets in the Remote Explorer

远程资源管理器允许您在远程主机上打开一个新的空窗口或直接打开您以前打开的文件夹。展开主机，然后单击要在此主机上打开的文件夹旁边的 打开文件夹 图标。

Remote Explorer open folder

管理扩展

VS Code 在两个位置之一运行扩展：本地 UI/客户端或远程 SSH 主机。虽然影响 VS Code UI 的扩展（如主题和代码片段）是本地安装的，但大多数扩展将驻留在 SSH 主机上。这可确保您拥有流畅的体验，并允许您从本地计算机在 SSH 主机上为给定的工作区安装任何所需的扩展。这样，您就可以从不同的计算机（包括您的扩展）继续您上次离开的地方。

如果您从扩展视图安装扩展，它将自动安装在正确的位置。安装后，您可以根据类别分组判断扩展的安装位置。

将有一个针对您的远程 SSH 主机的类别

Workspace Extension Category

还有一个 本地 - 已安装 类别

Local Extension Category

注意：如果您是扩展作者，并且发现您的扩展无法正常工作或安装在错误的位置，请参阅支持远程开发以了解详细信息。

实际上需要在远程运行的本地扩展将在 本地 - 已安装 类别中显示为灰色且禁用。选择 安装 以在远程主机上安装扩展。

Disabled Extensions w/Install Button

您还可以通过转到扩展视图，然后使用 本地 - 已安装 标题栏右侧的云按钮选择 在 SSH 中安装本地扩展：{主机名}，从而在 SSH 主机上安装所有本地安装的扩展。这将显示一个下拉菜单，您可以在其中选择要在 SSH 主机上安装哪些本地安装的扩展。

“始终安装”的扩展

如果有一些您希望始终安装在任何 SSH 主机上的扩展，您可以使用 settings.json 中的 remote.SSH.defaultExtensions 属性指定哪些扩展。例如，如果您想安装 GitLens 和 Resource Monitor 扩展，请按如下方式指定它们的扩展 ID

"remote.SSH.defaultExtensions": [
    "eamodio.gitlens",
    "mutantdino.resourcemonitor"
]

高级：强制扩展在本地/远程运行

扩展通常被设计和测试为在本地或远程运行，而不是两者都运行。但是，如果扩展支持，您可以强制它在 settings.json 文件中的特定位置运行。

例如，以下设置将强制 Docker 扩展在本地运行，而 Remote - SSH：编辑配置文件扩展在远程运行，而不是它们的默认设置

"remote.extensionKind": {
    "ms-azuretools.vscode-docker": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

"ui" 而不是 "workspace" 的值将强制扩展在本地 UI/客户端运行。通常，除非扩展的文档中另有说明，否则这只应在测试中使用，因为它可能会破坏扩展。有关详细信息，请参阅有关支持远程开发的文章。

转发端口/创建 SSH 隧道

有时，在开发过程中，您可能需要访问远程计算机上未公开的端口。有两种方法可以使用 SSH 隧道来实现此目的，该隧道会将所需的远程端口“转发”到您的本地计算机。

临时转发端口

连接到主机后，如果您想在会话期间临时转发一个新端口，请从命令面板中选择 转发端口（F1，⇧⌘P（Windows，Linux Ctrl+Shift+P））或选择 端口视图 中的 添加端口 按钮。您可以在底部面板中看到端口视图，或者通过运行命令 端口：聚焦于端口视图 来查看。

Forward port button

系统会要求您输入要转发的端口，您可以为其命名。

Adding a new port

通知将告诉您应使用哪个 localhost 端口来访问远程端口。例如，如果您转发了侦听端口 3000 的 HTTP 服务器，则通知可能会告诉您它已映射到 localhost 上的端口 4123，因为 3000 已在使用中。然后，您可以使用 https://127.0.0.1:4123 连接到此远程 HTTP 服务器。

如果您以后需要访问它，则此相同信息在远程资源管理器的 转发的端口 部分中可用。

如果您希望 VS Code 记住您转发的任何端口，请在设置编辑器（⌘,（Windows，Linux Ctrl+,））中选中 远程：还原转发的端口 或在 settings.json 中设置 "remote.restoreForwardedPorts": true。

Restore forwarded ports setting

更改隧道上的本地端口

如果您希望隧道的本地端口与远程服务器的端口不同，您可以通过 转发的端口 面板更改此设置。

右键单击要修改的隧道，然后在上下文菜单中选择 更改本地地址端口。

Change Local Address Port

始终转发端口

如果您有始终想要转发的端口，您可以使用您用于记住主机和高级设置的同一个 SSH 配置文件中的 LocalForward 指令。

例如，如果您想转发端口 3000 和 27017，您可以按如下方式更新文件

Host remote-linux-machine
    User myuser
    HostName remote-linux-machine.mydomain
    LocalForward 127.0.0.1:3000 127.0.0.1:3000
    LocalForward 127.0.0.1:27017 127.0.0.1:27017

在远程主机上打开终端

从 VS Code 在远程主机上打开终端很简单。连接后，您在 VS Code 中打开的任何终端窗口（终端 > 新终端）都将自动在远程主机上运行，而不是在本地运行。

您还可以从同一终端窗口使用 code 命令行来执行许多操作，例如在远程主机上打开新文件或文件夹。键入 code --help 以查看可从命令行使用的所有选项。

Using the code CLI

在 SSH 主机上调试

连接到远程主机后，您可以像在本地运行应用程序时一样使用 VS Code 的调试器。例如，如果您在 launch.json 中选择一个启动配置并开始调试（F5），则应用程序将在远程主机上启动并将调试器附加到它。

有关在 .vscode/launch.json 中配置 VS Code 的调试功能的详细信息，请参阅调试文档。

SSH 主机特定设置

当您连接到 SSH 主机时，也会重复使用 VS Code 的本地用户设置。虽然这可以使您的用户体验保持一致，但您可能希望在本地计算机和每个主机之间更改其中一些设置。幸运的是，连接到主机后，您还可以通过从命令面板运行 首选项：打开远程设置 命令（F1，⇧⌘P（Windows，Linux Ctrl+Shift+P））或在设置编辑器中选择 远程 选项卡来设置特定于主机的设置。这些设置将覆盖您在连接到主机时已有的任何用户设置。并且工作区设置将覆盖远程和用户设置。

Host-specific settings tab

使用本地工具

Remote - SSH 扩展不支持直接同步源代码或使用本地工具来处理远程主机上的内容。但是，有两种方法可以使用常见工具来实现此目的，这些工具适用于大多数 Linux 主机。具体来说，您可以：

  1. 使用 SSHFS 挂载远程文件系统.
  2. 使用 rsync 将文件从远程主机同步到本地计算机或从本地计算机同步到远程主机.

SSHFS 是最方便的选择，不需要任何文件同步。但是，性能会明显慢于通过 VS Code 工作，因此最好用于单文件编辑和上传/下载内容。如果您需要使用一次性批量读取/写入多个文件的应用程序（例如本地源代码控制工具），则 rsync 是更好的选择。

已知限制

Remote - SSH 限制

  • 建议使用基于密钥的身份验证。为备用身份验证方法输入的密码和其他令牌不会被保存。
  • 不支持 Alpine Linux 和基于非 glibc 的 Linux SSH 主机。
  • 较旧的（社区支持的）Linux 发行版需要一些解决方法来安装所需的先决条件。
  • Windows 上不支持 PuTTY。
  • 如果使用 SSH 克隆 Git 存储库，并且您的 SSH 密钥带有密码，则在远程运行时，VS Code 的拉取和同步功能可能会挂起。可以使用不带密码的 SSH 密钥、使用 HTTPS 克隆，或者从命令行运行 git push 来解决此问题。
  • 本地代理设置不会在远程主机上重用，这可能会阻止扩展程序正常工作，除非在远程主机上配置了适当的代理信息（例如，具有适当代理信息的全局 HTTP_PROXY 或 HTTPS_PROXY 环境变量）。
  • 有关与 SSH 相关的活动问题列表，请参阅此处。

Docker 扩展限制

如果您从 WSL、Remote - Tunnels 或 Remote - SSH 窗口使用 Docker 或 Kubernetes 扩展，则在 Docker 或 Kubernetes 视图中使用附加 Visual Studio Code 上下文菜单操作时，会要求您再次从可用容器中选择。

扩展限制

许多扩展程序在远程 SSH 主机上无需修改即可工作。但是，在某些情况下，某些功能可能需要更改。如果您遇到扩展问题，这里有常见问题和解决方案的摘要，您可以在报告问题时向扩展作者提及。

此外，由于扩展中仅支持 x86_64 的本机模块或运行时，因此安装在 ARMv7l (AArch32) / ARMv8l (AArch64) 设备上的某些扩展程序可能无法工作。在这种情况下，扩展程序需要通过为 ARMv7l / ARMv8l 编译/包含二进制文件来选择支持这些平台。

常见问题

如何在 ... 上设置 SSH 客户端？

有关详细信息，请参阅安装受支持的 SSH 客户端。

如何在 ... 上设置 SSH 服务器？

有关为您的主机设置 SSH 服务器的详细信息，请参阅安装受支持的 SSH 服务器。

我可以使用密码等其他/额外的身份验证机制登录到我的 SSH 服务器吗？

可以，系统应该会自动提示您输入令牌或密码。但是，密码不会被保存，因此通常使用基于密钥的身份验证更加方便。

如何修复有关“权限错误”的 SSH 错误？

有关解决这些类型错误的详细信息，请参阅修复 SSH 文件权限错误。

远程 SSH 主机上需要安装哪些 Linux 包/库？

大多数 Linux 发行版不需要额外的依赖项安装步骤。对于 SSH，Linux 主机需要安装 Bash (/bin/bash)、tar 以及 curl 或 wget 中的任意一个，某些精简发行版可能缺少这些实用工具。远程开发还需要内核 >= 3.10、glibc >=2.17、libstdc++ >= 3.4.18。目前仅支持基于 glibc 的发行版，因此Alpine Linux 不受支持。

有关详细信息，请参阅Linux 先决条件。

VS Code Server 在远程计算机/VM 上运行时，有哪些连接要求？

安装 VS Code Server 需要本地计算机具有出站 HTTPS (端口 443) 连接到：

  • update.code.visualstudio.com
  • vscode.blob.core.windows.net
  • *.vo.msecnd.net (Azure CDN)

默认情况下，Remote - SSH 将尝试在远程主机上下载，并在建立连接后回退到在本地下载 VS Code Server 并远程传输它。您可以使用 remote.SSH.localServerDownload 设置来更改此行为，以始终在本地下载然后再传输，或者从不在本地下载。

您可以使用 Extensions: Install from VSIX... 命令手动安装扩展程序，而无需 Internet 连接，但是如果您使用扩展面板安装扩展程序，则您的本地计算机和 VS Code Server 服务器将需要出站 HTTPS (端口 443) 访问：

  • marketplace.visualstudio.com
  • *.vo.msecnd.net (Azure CDN)
  • *.gallerycdn.vsassets.io (Azure CDN)

最后，某些扩展程序（如 C#）会从 download.microsoft.com 或 download.visualstudio.microsoft.com 下载辅助依赖项。其他扩展程序（如Visual Studio Live Share）可能具有其他连接要求。如果您遇到问题，请参阅扩展的文档以获取详细信息。

服务器和 VS Code 客户端之间的所有其他通信都是通过经过身份验证的安全 SSH 隧道完成的。

我可以在位于远程 SSH 主机上的源代码上使用本地工具吗？

可以。通常，这是通过使用 SSHFS 或通过使用 rsync 在本地计算机上获取文件副本。SSHFS 挂载远程文件系统非常适合需要编辑单个文件或浏览源树的情况，并且不需要同步步骤即可使用。但是，它不适合使用诸如批量管理文件的源代码控制工具之类的工具。在这种情况下，rsync 方法更好，因为您可以在本地计算机上获得远程源代码的完整副本。有关详细信息，请参阅提示和技巧。

当我只有对远程主机的 SFTP/FTP 文件系统访问权限（没有 shell 访问权限）时，可以使用 VS Code 吗？

某些云平台仅为开发人员提供远程文件系统访问权限，而不是直接 shell 访问权限。VS Code 远程开发并非针对这种情况而设计，因为它否定了性能和用户体验的优势。

但是，这种情况通常可以通过结合诸如SFTP 之类的扩展与Node.js、Python、C# 或其他语言的远程调试功能来处理。

作为扩展作者，我需要做什么？

VS Code 扩展 API 抽象了本地/远程细节，因此大多数扩展程序无需修改即可工作。但是，鉴于扩展程序可以使用它们想要的任何 node 模块或运行时，在某些情况下可能需要进行调整。我们建议您测试扩展程序，以确保不需要更新。有关详细信息，请参阅支持远程开发。

问题或反馈

12/11/2024