参加你附近的 ，了解 VS Code 中的 AI 辅助开发。

使用 SSH 进行远程开发

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

无需将源代码放在本地机器上即可获得这些好处，因为该扩展直接在远程机器上运行命令和其他扩展。该扩展将在远程操作系统上安装 VS Code Server；该服务器独立于远程操作系统上任何现有的 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 位）。
  • Windows 10 / Server 2016/2019 (1803+) 使用官方 OpenSSH 服务器。
  • 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 中使用其他远程扩展，可以选择安装Remote Development 扩展包。

SSH 主机设置

  1. 如果你尚未设置 SSH 主机，请按照Linux、Windows 10 / Server (1803+) 或 macOS SSH 主机的说明进行操作，或者在 Azure 上创建虚拟机。

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

    在设置编辑器中

    Listen on socket VS Code setting

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

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

连接到远程主机

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

  1. 通过从终端/PowerShell 窗口运行以下命令来验证你是否可以连接到 SSH 主机，并相应地替换 user@hostname。

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

  2. 在 VS Code 中，从命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）中选择 Remote-SSH: Connect to Host...，并使用与步骤 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. 按照安装步骤在你的远程主机上安装 Docker，并在本地安装 VS Code 和开发容器扩展。
  2. 可选： 设置 SSH 基于密钥的身份验证到服务器，这样你就不需要多次输入密码。
  3. 按照 Remote - SSH 扩展的快速入门连接到主机并在那里打开一个文件夹。
  4. 从命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用 开发容器：在容器中重新打开 命令。

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

断开与远程主机的连接

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

记住主机和高级设置

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

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

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

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 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...，或在远程资源管理器的 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 文件中强制它在特定位置运行。

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

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

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

转发端口/创建 SSH 隧道

有时在开发时，你可能需要访问远程机器上未公开的端口。有两种方法可以使用 SSH 隧道来完成此操作，该隧道将所需的远程端口“转发”到你的本地机器。

临时转发端口

连接到主机后，如果你想在会话期间临时转发新端口，请从命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）选择 Forward a Port，或在端口视图中选择添加端口按钮。你可以在底部面板中看到端口视图，或者运行命令 Ports: Focus on Ports View。

Forward port button

系统会要求你输入要转发的端口，你可以为其指定一个名称。

Adding a new port

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

如果你以后需要访问，这些信息在远程资源管理器的已转发端口部分中也可用。

如果你希望 VS Code 记住你已转发的任何端口，请在设置编辑器（⌘, (Windows, Linux Ctrl+,)）中勾选 Remote: Restore Forwarded Ports，或在 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)）运行 Preferences: Open Remote Settings 命令，或通过在设置编辑器中选择远程选项卡来设置主机特定的设置。这些设置将在你连接到主机时覆盖任何已有的用户设置。工作区设置将覆盖远程和用户设置。

Host-specific settings tab

使用本地工具

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

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

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

已知限制

远程 - SSH 限制

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

容器工具扩展限制

如果您正在从 WSL、Remote - Tunnels 或 Remote - SSH 窗口使用 Container Tools 或 Kubernetes 扩展，则在容器资源管理器或 Kubernetes 视图中使用 Attach Visual Studio Code 上下文菜单操作将要求第二次从可用容器中进行选择。

扩展限制

许多扩展无需修改即可在远程 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)、tar 和 curl 或 wget，这些实用程序可能在某些精简发行版中缺失。远程开发还需要内核 >= 3.10、glibc >=2.17、libstdc++ >= 3.4.18。目前仅支持基于 glibc 的发行版，因此 Alpine Linux 不受支持。

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

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

VS Code Server 的安装要求你的本地机器具有出站 HTTPS（端口 443）连接到：

  • update.code.visualstudio.com
  • vscode.download.prss.microsoft.com

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

你可以使用扩展：从 VSIX 安装...命令在没有互联网连接的情况下手动安装扩展，但如果你使用扩展面板安装扩展，你的本地机器和 VS Code Server 服务器将需要出站 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 远程开发并非为此用例而设计，因为它会抵消性能和用户体验方面的优势。

但是，此用例通常可以通过将 SFTP 等扩展与针对 Node.js、Python、C# 或其他语言的远程调试功能结合使用来处理。

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

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

问题或反馈

09/11/2025