使用SSH进行远程开发

Name: Visual Studio Code
Author: Microsoft

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

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

SSH架构

这使得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 / Server 2016/2019 (1803+)。
macOS 10.14+ (Mojave) 启用了远程登录的SSH主机。
远程主机需要1 GB RAM，但建议至少2 GB RAM和双核CPU。

其他基于glibc的Linux发行版，适用于x86_64、ARMv7l（AArch32）和ARMv8l（AArch64），如果它们具备所需的先决条件，应该可以正常工作。有关先决条件的信息以及如何启动和运行社区支持的发行版的提示，请参阅使用Linux进行远程开发文章。

虽然支持ARMv7l（AArch32）和ARMv8l（AArch64），但由于扩展中使用了x86原生代码，安装在这些设备上的一些扩展可能无法正常工作。

安装

要开始，你需要：

如果尚未安装，请安装一个OpenSSH兼容的SSH客户端。
安装 Visual Studio Code 或 Visual Studio Code Insiders。
安装Remote-SSH扩展。如果您计划在VS Code中使用其他远程扩展，您可以选择安装Remote Development扩展包。

SSH 主机设置

如果您没有设置SSH主机，请按照Linux、Windows 10 / Server (1803+)或macOS SSH主机的指示操作，或者创建一个Azure上的虚拟机。
可选： 如果您的Linux或macOS SSH主机将被多个用户同时访问，请考虑在VS Code的用户设置中启用Remote.SSH: Remote Server Listen On Socket以提高安全性。

在设置编辑器中：

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

连接到远程主机

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

通过从终端/PowerShell窗口运行以下命令来验证您可以连接到SSH主机，适当地替换user@hostname。
```
ssh user@hostname
# Or for Windows when using a domain / AAD account
ssh user@domain@hostname
```
在 VS Code 中，从命令面板中选择 Remote-SSH: Connect to Host...（F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)），并使用与步骤 1 中相同的 user@hostname。
如果VS Code无法自动检测您正在连接的服务器类型，您将被要求手动选择类型。

一旦你选择了一个平台，它将被存储在VS Code 设置中的remote.SSH.remotePlatform属性下，以便你可以随时更改它。
片刻之后，VS Code 将连接到 SSH 服务器并进行设置。VS Code 将通过进度通知保持您的最新状态，您可以在 Remote - SSH 输出通道中查看详细日志。

提示：连接挂起或失败？查看故障排除提示以获取解决常见问题的信息。

如果您看到关于SSH文件权限的错误，请参阅修复SSH文件权限错误部分。
连接后，您将进入一个空窗口。您可以随时参考状态栏查看您连接的主机。

点击状态栏项目将在您连接时提供远程命令列表。
然后，您可以像在本地一样，使用文件 > 打开...或文件 > 打开工作区...在远程机器上打开任何文件夹或工作区！

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

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

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

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

要这样做：

按照安装步骤在远程主机上安装Docker，并在本地安装VS Code和Dev Containers扩展。
可选： 设置SSH 基于密钥的认证到服务器，这样你就不需要多次输入密码。
按照快速开始的步骤，使用Remote - SSH扩展连接到主机并在那里打开一个文件夹。
使用Dev Containers: Reopen in Container命令从命令面板（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连接信息。您可以输入主机名：

远程资源管理器SSH主机输入

或者是从命令行连接到主机时使用的完整 ssh 命令：

远程资源管理器SSH命令输入

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

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

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

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

从这一点开始，当您从命令面板（F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)）选择Remote-SSH: Connect to Host...或在Remote Explorer的SSH Targets部分时，主机将出现在主机列表中。

远程资源管理器中的SSH目标

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

远程资源管理器打开文件夹

管理扩展

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

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

将会有一个类别用于您的远程SSH主机：

工作区扩展类别

还有一个本地安装类别：

本地扩展类别

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

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

禁用扩展并带有安装按钮

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

"始终安装"的扩展

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

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

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

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

例如，下面的设置将强制Docker扩展在本地运行，而Remote - SSH: Editing Configuration Files扩展将远程运行，而不是它们的默认设置：

"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)）或在端口视图中选择添加端口按钮。您可以在底部面板中看到端口视图，或者通过运行命令Ports: Focus on Ports View来查看。

转发端口按钮

您将被要求输入您想要转发的端口，并可以为其命名。

添加新端口

通知会告诉你应该使用的本地主机端口来访问远程端口。例如，如果你转发了一个监听在端口3000上的HTTP服务器，通知可能会告诉你它被映射到了本地主机的端口4123，因为3000已经被占用了。然后你可以使用http://localhost:4123连接到这个远程HTTP服务器。

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

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

恢复转发的端口设置

更改隧道上的本地端口

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

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

更改本地地址端口

始终转发端口

如果您有始终希望转发的端口，您可以在用于记住主机和高级设置的同一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以查看命令行中所有可用的选项。

使用代码 CLI

在SSH主机上进行调试

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

请参阅调试文档，了解如何在.vscode/launch.json中配置VS Code的调试功能。

SSH 主机特定设置

VS Code 的本地用户设置在你连接到 SSH 主机时也会被重用。虽然这保持了你的用户体验一致，但你可能希望在本地机器和每个主机之间改变一些设置。幸运的是，一旦你连接到一个主机，你也可以通过从命令面板运行 Preferences: Open Remote Settings 命令（F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)）或在设置编辑器中选择 Remote 选项卡来设置特定于主机的设置。这些设置将覆盖你在连接主机时拥有的任何用户设置。而工作区设置将覆盖远程和用户设置。

主机特定设置选项卡

使用本地工具

Remote - SSH 扩展不直接支持同步源代码或使用本地工具与远程主机上的内容进行交互。然而，有两种使用常见工具的方法可以与大多数 Linux 主机配合使用。具体来说，您可以：

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

已知限制

远程 - SSH 限制

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

Docker 扩展限制

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

扩展限制

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

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

常见问题

如何在...上设置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 服务器在远程机器/虚拟机上运行时需要满足哪些连接要求？

安装VS Code服务器需要您的本地机器具有对以下地址的出站HTTPS（端口443）连接：

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

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

您可以在没有互联网连接的情况下使用扩展：从VSIX安装...命令手动安装扩展，但如果您使用扩展面板安装扩展，您的本地机器和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 模块或运行时，有时可能需要进行调整。我们建议您测试您的扩展，以确保不需要更新。详情请参见支持远程开发。

问题或反馈

参见技巧与窍门或常见问题解答。
在Stack Overflow上搜索。
添加一个功能请求或报告问题。
为我们的文档或VS Code本身做出贡献。
详情请参阅我们的CONTRIBUTING指南。

12/11/2024