使用 SSH 进行远程开发

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

由于扩展直接在远程机器上运行命令和其他扩展，因此无需在本地机器上存放源代码即可获得这些好处。扩展将在远程操作系统上安装 VS Code 服务器；服务器独立于远程操作系统上的任何现有 VS Code 安装。

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

入门指南

注意：在阅读完此主题后，您可以开始使用入门SSH教程。

系统要求

本地： 一个支持的OpenSSH兼容的SSH客户端也必须安装。

远程 SSH 主机：正在运行的 SSH 服务器 于：

• x86_64 Debian 8+，Ubuntu 16.04+，CentOS / RHEL 7+。
• ARMv7l (AArch32) Raspberry Pi 操作系统（以前称为 Raspbian）Stretch/9+（32位）。
• ARMv8l (AArch64) Ubuntu 18.04+ (64位).
• Windows 10 / Server 2016/2019 (1803+) 使用 官方 OpenSSH 服务器.
• macOS 10.14+ (Mojave) SSH 主机与 远程登录已启用.
• 远程主机需要1 GB内存，但至少需要2 GB内存和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. 安装远程 SSH 扩展。如果您计划在 VS Code 中与其他远程扩展一起工作，您可以选择安装远程开发扩展包。

SSH主机设置

1. 如果您还没有设置SSH主机，请按照Linux、Windows 10 / Server (1803+)或macOS的说明设置SSH主机或创建一个Azure上的VM。

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

   在设置编辑器中：

   

   请参阅小贴士和技巧文章了解详情。

3. 可选： 虽然支持基于密码的认证，但我们建议为您的主机设置基于密钥的认证。详情请参阅提示和技巧文章。

连接到远程主机

要首次连接到远程主机，请按照以下步骤操作：

1. 验证您是否可以通过在终端 / PowerShell Windows中运行以下命令连接到 SSH 主机，将 用户@主机名适当的情况下。

   ssh user@hostname
   # 或在 Windows 上使用域 / AAD 账户时
   ssh user@domain@hostname
   

2. 在 VS Code 中，从命令面板（`F1`，`⇧⌘P`（Windows, Linux `Ctrl+Shift+P`）选择“Remote-SSH: Connect to Host...”并使用相同的用户@主机名如第1步所述。

   

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

   

   一旦你选择了一个平台，它将被存储在VS Code 设置中的远程.SSH.远程平台属性，您可以随时更改。

4. 稍后，VS Code将连接到SSH服务器并进行设置。VS Code将通过进度通知使您保持最新状态，您可以在 中查看详细的日志。远程 - SSH输出通道。

   提示： 连接悬挂或失败？请参阅 故障排除提示 以了解解决常见问题的信息。

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

5. 连接后，您将看到一个空白Windows。您始终可以参考状态栏以查看您连接到哪个主机。

   

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

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

   

从这里，安装任何扩展，连接到主机时使用，并开始编辑！

注意： 在 ARMv7l / ARMv8l 上 glibcSSH主机，由于扩展内部有x86编译的原生代码，某些扩展可能无法正常工作。

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

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

要这样做：

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

其余部分Dev Containers快速入门可直接应用。您可以了解更多关于Dev Containers扩展的信息，请参阅其文档。您还可以查看在远程Docker主机上开发文章以获取其他选项，如果此模型不能满足您的需求。

从远程主机断开连接

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

记住主机和高级设置

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

为了使设置变得简单，该扩展可以引导您添加主机，而无需手动编辑此文件。

首先选择 Remote-SSH: 添加新的 SSH 主机... 从命令面板 (F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)) 或点击活动栏中的 添加新的 图标在 SSH 远程资源管理器 中。

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

或者全部安全外壳协议用于从命令行连接到主机的命令：

最后，您将被要求选择一个配置文件来使用。您还可以设置"remote.SSH.configFile"您的用户属性settings.json如果您想使用不同于列出的配置文件，请更改文件。扩展程序会处理其余部分！

例如，输入ssh -i ~/.ssh/id_rsa-remote-ssh yourname@remotehost.yourcompany.com在输入框中会生成此条目：

主机 remotehost.yourcompany.com
    用户 yourname
    主机名 another-host-fqdn-or-ip-goes-here
    证书文件 ~/.ssh/id_rsa-remote-ssh

参见提示和技巧，了解生成此处显示的密钥的详细信息。您可以使用任何支持SSH配置文件格式的工具手动编辑此文件，因此这只是一个示例。

从这一点开始，当您选择Remote-SSH: 连接到主机... 从命令面板 (F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)) 或在 SSH 目标 部分的 远程资源管理器 中，主机将出现在主机列表中。

该远程资源管理器允许您在远程主机上打开一个新的空Windows或直接打开您之前打开的文件夹。展开主机并点击打开文件夹图标，以在主机上打开您想要的文件夹。

管理扩展

VS Code 在两个地方之一运行扩展：在用户界面/客户端本地运行，或在 SSH 主机上远程运行。 影响 VS Code 用户界面的扩展（如主题和片段）安装在本地，而大多数扩展将存储在 SSH 主机上。 这确保了您有一个流畅的体验，并允许您从本地机器在给定的 SSH 主机上安装任何所需的扩展。 这样，您可以在不同的机器上从相同的地方开始，并带有您的扩展。

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

将有一个类别来容纳您的远程 SSH 主机：

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

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

需要在远程运行的本地扩展将在 本地 - 已安装 分类中显示为变暗和禁用。选择 安装 来在您的远程主机上安装扩展。

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

“始终安装”的扩展程序

如果你希望在任何 SSH 主机上始终安装某些扩展，可以使用远程.SSH.默认扩展物业在settings.json例如，如果你想安装GitLens和资源监视器扩展，请按如下方式指定它们的扩展ID：

"remote.SSH.defaultExtensions"：
    "eamodio.gitlens"，
    "mutantdino.resourcemonitor"
]

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

扩展程序通常被设计和测试为要么本地运行，要么远程运行，但不能两者都支持。然而，如果扩展程序支持，你可以强制它在你指定的某个位置运行。settings.json文件。

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

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

一个值"ui"而不是"工作区" 将强制在本地UI/客户端上运行扩展。通常，除非扩展文档中另有说明，否则仅应在此情况下使用，因为它 可能会破坏扩展。有关详细信息，请参阅 支持远程开发 文章。

转发端口 / 创建 SSH 隧道

在开发过程中，有时您可能需要访问远程机器上的一个端口，而这个端口没有公开暴露。有两种方法可以做到这一点，使用一个SSH隧道将所需的远程端口“转发”到您的本地机器。

暂时转发端口

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

您将被要求输入要转发的端口，并且您可以给它取一个名字。

通知将告知您应使用哪个本地主机端口来访问远程端口。例如，如果您转发了一个监听3000端口的HTTP服务器，通知可能会告诉您它已映射到本地主机的4123端口，因为3000端口已被使用。然后，您可以使用以下方式连接到这个远程HTTP服务器：http://localhost:4123输入：.

同样的信息也可以在转发端口部分找到，如果你以后需要访问它。

如果您希望 VS Code 记住您已转发的任何端口，请在设置编辑器中勾选 远程：恢复已转发的端口 (⌘, (Windows, Linux Ctrl+,)) 或设置 "remote.restoreForwardedPorts": true在settings.json输入：.

更改隧道上的本地端口

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

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

总是转发端口

如果你有总是想要转发的端口，你可以使用本地转发 指令在您用来 记住主机和高级设置的同一SSH配置文件中。

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

主机 远程Linux机器
    用户 myuser
    主机名 remote-linux-machine.mydomain
    本地转发 127.0.0.1:3000 127.0.0.1:3000
    本地转发 127.0.0.1:27017 127.0.0.1:27017

在远程主机上打开终端

从 VS Code 在远程主机上打开终端非常简单。一旦连接，任何在 VS Code 中打开的终端Windows（终端 > 新建终端）将自动在远程主机上运行，而不是在本地。

您还可以使用代码从同一个终端Windows使用命令行执行一些操作，例如在远程主机上打开新的文件或文件夹。输入代码 --help查看所有可通过命令行提供的选项。

在 SSH 主机上调试

一旦你连接到远程主机，你就可以以与在本地运行应用程序时相同的方式使用 VS Code 的调试器。例如，如果你在launch.json 并开始调试 (F5)，应用程序将在远程主机上启动并附加调试器。

请参阅调试文档，了解在中配置 VS Code 调试功能的详细信息.vscode/launch.json输入：.

SSH 主机特定设置

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

使用本地工具

The Remote - SSH扩展不直接支持同步源代码或在远程主机上使用本地工具。然而，有 two种方法可以使用 common tools 来实现这个功能，这些工具在大多数 Linux 主机上都可以工作。具体来说，你可以：

1. 使用SSHFS挂载远程文件系统.
2. 使用 将文件同步到/从远程主机到您的本地机器rsync输入：.

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

已知限制

远程 - SSH 限制

• 建议使用基于密钥的认证。 其他认证方法 输入的密码和其他令牌不会被保存。
• Alpine Linux 和基于非glibc的Linux SSH主机不被支持。
• 较旧的（社区支持的）Linux发行版需要使用工作arounds来安装所需的前提条件。
• PuTTY在Windows上不受支持。
• 如果你通过 SSH 克隆一个 Git 仓库，并且你的 SSH 密钥有密码，VS Code 的拉取和同步功能在远程运行时可能会卡住。可以使用没有密码的 SSH 密钥，或者使用 HTTPS 克隆，或者运行git 推送从命令行解决此问题。
• 本地代理设置不会在远程主机上被重新使用，除非在远程主机上配置了适当的代理信息（例如全局代理信息），这可能会导致扩展无法正常工作。HTTP代理或HTTPS_PROXY设置环境变量以包含适当的代理信息。
• 见这里有关于SSH的活跃问题列表。

容器工具扩展限制

如果您正在从WSL、Remote - Tunnels或Remote - SSHWindows使用Container Tools或Kubernetes扩展，使用附加Visual Studio Code上下文菜单操作在Container Explorer或Kubernetes视图中将再次询问您选择可用容器。

扩展限制

许多扩展可以在远程 SSH 主机上运行而无需修改。然而，在某些情况下，某些功能可能需要更改。如果你遇到扩展问题，有常见问题和解决方案的总结，在报告问题时可以提到扩展作者。

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

常见问题

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

参见安装支持的 SSH 客户端 了解详细信息。

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

参见安装受支持的SSH服务器了解有关为主机设置SSH服务器的详细信息。

我可以使用其他/附加的认证机制，如密码，登录到我的SSH服务器吗？

是的，您应该会被自动提示输入您的令牌或密码。然而，密码不会被保存，因此使用基于密钥的认证通常更方便。

如何解决 SSH 错误关于“权限错误”？

参见修复 SSH 文件权限错误了解有关解决这些错误的详细信息。

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

大多数 Linux 发行版将不需要额外的依赖安装步骤。对于 SSH，Linux 主机需要安装 Bash (/bin/bash),火柴，和任意库尔或wget 已安装并且这些实用程序可能在某些精简的发行版中缺失。远程开发还要求内核 >= 3.10，glibc >=2.17，libstdc++ >= 3.4.18。目前仅支持基于glibc的发行版，因此Alpine Linux不被支持。

参见Linux 先决条件 了解详情。

VS Code Server 在远程机器 / 虚拟机上运行时的连接要求是什么？

安装 VS Code Server 需要您的本地机器具有到以下地址的 outbound HTTPS (端口 443) 连接性：

• 更新.code.visualstudio.com
• vscode下载.prss.microsoft.com

默认情况下，Remote - SSH 将尝试在远程主机上下载，并在建立连接后回退到在本地下载 VS Code Server 并远程传输。您可以使用以下选项更改此行为

您可以在没有互联网连接的情况下手动安装扩展，使用 扩展：从 VSIX 安装... 命令，但如果使用扩展面板安装扩展，您的本地机器和 VS Code Server 服务器将需要访问以下内容的 outbound HTTPS (端口 443)：

• marketplace.visualstudio.com
• *.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 远程开发并不是为这种用例而设计的，因为这会 negates 性能和用户体验的好处。

然而，通常可以通过结合像SFTP这样的扩展与远程调试功能来处理这种用例，适用于Node.js、Python、C#或其他语言。

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

VS Code 扩展 API 抽象掉了本地/远程的细节，因此大多数扩展在不修改的情况下应该可以正常工作。然而，由于扩展可以使用任何他们想要的 node 模块或运行时，存在需要进行调整的情况。我们建议您测试您的扩展，以确保不需要更新。请参阅支持远程开发了解详细信息。

问题或反馈

• 查看小贴士和技巧或常见问题。
• 搜索 Stack Overflow。
• 添加一个功能请求或报告一个问题。
• 贡献到 我们的文档 或 VS Code 本身.
• 请参阅我们的贡献指南了解详情。