远程开发提示和技巧

本文介绍了每个 Visual Studio Code远程开发扩展的故障排除提示和技巧。有关设置和使用每个特定扩展的详细信息，请参阅SSH、Containers和WSL文章。或者尝试介绍性教程来帮助您在远程环境中快速运行。

有关GitHub Codespaces的提示和问题，请参阅GitHub Codespaces 文档。

SSH提示

SSH 功能强大且灵活，但这也增加了一些设置的复杂性。本节包含一些在不同环境中启动并运行远程 SSH 扩展的提示和技巧。

配置基于密钥的身份验证

SSH 公钥身份验证是一种方便、高安全性的身份验证方法，它将本地“私钥”与与 SSH 主机上的用户帐户关联的“公钥”相结合。本节将引导您了解如何生成这些密钥并将它们添加到主机。

提示： PuTTY for Windows 不是受支持的客户端，但您可以转换 PuTTYGen 密钥。

快速入门：使用 SSH 密钥

为远程主机设置基于 SSH 密钥的身份验证。首先，我们将创建一个密钥对，然后将公钥复制到主机。

创建本地 SSH 密钥对

检查您的本地计算机上是否已有 SSH 密钥。该目录通常位于~/.ssh/id_ed25519.pubmacOS / Linux 上，以及.sshWindows 上的用户配置文件文件夹中的目录（例如C:\Users\your-user\.ssh\id_ed25519.pub）。

如果您没有密钥，请在本地终端/PowerShell 中运行以下命令来生成 SSH 密钥对：

ssh-keygen -t ed25519 -b 4096

提示：没有ssh-keygen？安装受支持的 SSH 客户端。

限制私钥文件的权限

• 对于 macOS / Linux，运行以下 shell 命令，如有必要，请替换私钥的路径：

  chmod 400 ~/.ssh/id_ed25519
  

• 对于 Windows，在 PowerShell 中运行以下命令以授予对您的用户名的显式读取访问权限：

  icacls "privateKeyPath" /grant :R
  

  然后导航到 Windows 资源管理器中的私钥文件，右键单击并选择“属性”。选择安全选项卡 >高级>禁用继承>删除从此对象继承的所有权限。

授权您的 macOS 或 Linux 计算机进行连接

在本地终端窗口中运行以下命令之一，根据需要替换用户名和主机名，以将本地公钥复制到 SSH 主机。

• 连接到macOS 或 Linux SSH 主机：

  export USER_AT_HOST="your-user-name-on-host@hostname"
  export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
  
  ssh-copy-id -i "$PUBKEYPATH" "$USER_AT_HOST"
  

• 连接到Windows SSH 主机：

  export USER_AT_HOST="your-user-name-on-host@hostname"
  export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
  
  ssh $USER_AT_HOST "powershell New-Item -Force -ItemType Directory -Path \"\$HOME\\.ssh\"; Add-Content -Force -Path \"\$HOME\\.ssh\\authorized_keys\" -Value '$(tr -d '\n\r' < "$PUBKEYPATH")'"
  

  您可能需要验证SSH 主机上远程用户的文件夹authorized_keys中的文件是否归您所有，并且其他用户无权访问该文件。有关详细信息，请参阅OpenSSH wiki。.ssh

授权您的 Windows 计算机进行连接

在本地 PowerShell窗口中运行以下命令之一，根据需要替换用户名和主机名，以将本地公钥复制到 SSH 主机。

• 连接到macOS 或 Linux SSH 主机：

  $USER_AT_HOST="your-user-name-on-host@hostname"
  $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
  
  $pubKey=(Get-Content "$PUBKEYPATH" | Out-String); ssh "$USER_AT_HOST" "mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo '${pubKey}' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
  

• 连接到Windows SSH 主机：

  $USER_AT_HOST="your-user-name-on-host@hostname"
  $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
  
  Get-Content "$PUBKEYPATH" | Out-String | ssh $USER_AT_HOST "powershell `"New-Item -Force -ItemType Directory -Path `"`$HOME\.ssh`"; Add-Content -Force -Path `"`$HOME\.ssh\authorized_keys`" `""
  

  验证SSH 主机上远程用户的文件夹authorized_keys中的文件是否归您所有，并且其他用户无权访问该文件。有关详细信息，请参阅OpenSSH wiki。.ssh

使用专用密钥提高您的安全性

虽然在所有 SSH 主机上使用单个 SSH 密钥可能很方便，但如果任何人获得了您的私钥的访问权限，他们也将有权访问您的所有主机。您可以通过为开发主机创建单独的 SSH 密钥来防止这种情况。只需按照以下步骤操作：

1. 在不同的文件中生成单独的 SSH 密钥。

   macOS / Linux ：在本地终端中运行以下命令：

   ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519-remote-ssh
   

   Windows ：在本地 PowerShell中运行以下命令：

   ssh-keygen -t ed25519 -f "$HOME\.ssh\id_ed25519-remote-ssh"
   

2. 按照快速入门中的相同步骤在 SSH 主机上授权密钥，但将改为PUBKEYPATH文件id_ed25519-remote-ssh.pub。

3. 在 VS Code 中，运行Remote-SSH：在命令面板 ( F1 ) 中打开配置文件...，选择 SSH 配置文件，然后添加（或修改）主机条目，如下所示：

   Host name-of-ssh-host-here
       User your-user-name-on-host
       HostName host-fqdn-or-ip-goes-here
       IdentityFile ~/.ssh/id_ed25519-remote-ssh
   

   提示：您/也可以用于 Windows 路径。如果使用，\则需要使用两个斜杠。例如，C:\\path\\to\\my\\id_ed25519.

重用 PuTTYGen 中生成的密钥

如果您使用 PuTTYGen 为要连接的主机设置 SSH 公钥身份验证，则需要转换您的私钥，以便其他 SSH 客户端可以使用它。去做这个：

1. 本地打开 PuTTYGen并加载要转换的私钥。

2. 从应用程序菜单中选择“转换”>“导出 OpenSSH 密钥” 。将转换后的密钥保存到用户配置文件文件夹中的目录下的本地位置.ssh（例如C:\Users\youruser\.ssh）。

3. 验证这个新的本地文件是否归您所有，并且其他用户没有权限访问它。

4. 在 VS Code 中，运行Remote-SSH：在命令面板 ( F1 ) 中打开配置文件...，选择要更改的 SSH 配置文件，然后在配置文件中添加（或修改）主机条目，如下所示到文件：

   Host name-of-ssh-host-here
       User your-user-name-on-host
       HostName host-fqdn-or-ip-goes-here
       IdentityFile ~/.ssh/exported-keyfile-from-putty
   

提高多用户服务器的安全性

远程 - SSH 扩展安装并维护“VS Code 服务器”。服务器使用随机生成的密钥启动，任何与服务器的新连接都需要提供该密钥。密钥存储在远程磁盘上，只有当前用户可读。存在一个无需身份验证即可使用的 HTTP 路径/version。

默认情况下，服务器侦听localhost随机 TCP 端口，然后将其转发到本地计算机。如果您要连接到Linux 或 macOS主机，则可以切换到使用锁定到特定用户的 Unix 套接字。然后转发该套接字而不是端口。

注意：此设置会禁用连接多路复用，因此建议配置公钥身份验证。

配置它：

1. 确保您在 Windows、macOS 或 Linux 上有本地 OpenSSH 6.7+ SSH 客户端以及OpenSSH 6.7+ Linux 或 macOS 主机（Windows 不支持此模式）。

2. 通过在本地VS Code用户设置中启用 Remote.SSH : Remote Server Listen On Socket，将 Remote- SSH 切换到套接字模式。

   

3. 如果您已连接到 SSH 主机，请从命令面板 ( F1 ) 中选择Remote-SSH: Kill VS Code Server on Host...以便设置生效。

如果连接时遇到错误，您可能需要在 SSH 主机的sshd config上启用套接字转发。为此：

1. /etc/ssh/sshd_config在SSH 主机（非本地）上的文本编辑器（例如 vi、nano 或 pico）中打开。
2. 添加设置 AllowStreamLocalForwarding yes。
3. 重新启动 SSH 服务器。（在 Ubuntu 上，运行sudo systemctl restart sshd.）。
4. 重试。

对挂起或失败的连接进行故障排除

如果您在尝试连接时遇到 VS Code 挂起的问题（并且可能会超时），您可以采取一些措施来尝试解决该问题。

一般故障排除：删除服务器

有助于解决各种 Remote-SSH 问题的命令是Remote-SSH: Kill VS Code Server on Host。这将删除服务器，从而可以修复您可能会看到的各种问题和错误消息，例如“无法建立与server_name：VS Code 服务器无法启动”。

查看 VS Code 是否正在等待提示

在 VS Code 中启用remote.SSH.showLoginTerminal 设置并重试。如果系统提示您输入密码或令牌，请参阅启用备用 SSH 身份验证方法，了解有关减少提示频率的详细信息。

如果仍然遇到问题，请设置以下属性settings.json并重试：

"remote.SSH.showLoginTerminal": true,
"remote.SSH.useLocalServer": false

解决某些版本的 Windows OpenSSH 服务器的错误

由于适用于 Windows 的 OpenSSH 服务器的某些版本中存在错误，确定主机是否运行 Windows 的默认检查可能无法正常工作。Windows 1909 及更低版本附带的 OpenSSH 服务器不会出现这种情况。

幸运的是，您可以通过将以下内容添加到中，明确告诉 VS Code 您的 SSH 主机是否运行 Windows 来解决此问题settings.json：

"remote.SSH.useLocalServer": false

您还可以使用以下属性强制 VS Code 将特定主机识别为 Windows：

"remote.SSH.remotePlatform": {
    "host-in-ssh-config-or-fqdn": "windows"
}

已合并修复程序，因此应在高于 8.1.0.0 的服务器版本中解决此问题。

在远程主机上启用 TCP 转发

远程 - SSH 扩展利用 SSH 隧道来促进与主机的通信。在某些情况下，您的 SSH 服务器上可能会禁用此功能。要查看这是否是问题所在，请在输出窗口中打开“远程 - SSH”类别并检查以下消息：

open failed: administratively prohibited: open failed

如果您确实看到该消息，请按照以下步骤更新 SSH 服务器的sshd 配置：

1. 在SSH 主机（非本地）上打开/etc/ssh/sshd_config或在文本编辑器（例如 Vim、nano、Pico 或记事本）中打开。C:\ProgramData\ssh\sshd_config
2. 添加设置 AllowTcpForwarding yes。
3. 重新启动 SSH 服务器。（在 Ubuntu 上，运行sudo systemctl restart sshd。在 Windows 上，在管理 PowerShell 中运行Restart-Service sshd）。
4. 重试。

在 SSH 配置文件中设置 ProxyCommand 参数

如果您位于代理后面并且无法连接到 SSH 主机，您可能需要在本地SSH 配置文件中使用ProxyCommand主机的参数。您可以阅读这篇SSH ProxyCommand 文章以获取其使用示例。

确保远程计算机可以访问互联网

远程计算机必须具有 Internet 访问权限才能从 Marketplace 下载 VS Code 服务器和扩展。有关连接要求的详细信息，请参阅常见问题解答。

在远程主机上设置 HTTP_PROXY / HTTPS_PROXY

如果您的远程主机位于代理后面，您可能需要在SSH 主机上设置 HTTP_PROXY 或 HTTPS_PROXY 环境变量。打开~/.bashrc文件添加以下内容（替换proxy.fqdn.or.ip:3128为适当的主机名/IP 和端口）：

export HTTP_PROXY=http://proxy.fqdn.or.ip:3128
export HTTPS_PROXY=$HTTP_PROXY

# Or if an authenticated proxy
export HTTP_PROXY=http://username:password@proxy.fqdn.or.ip:3128
export HTTPS_PROXY=$HTTP_PROXY

解决安装/tmp问题noexec

某些远程服务器设置为禁止从/tmp. VS Code 将其安装脚本写入系统临时目录并尝试从那里执行它。您可以与系统管理员一起确定是否可以解决此问题。

检查安装过程中是否启动了不同的 shell

某些用户从其SSH 主机.bash_profile上的启动脚本或其他启动脚本启动不同的 shell ，因为他们想要使用与默认 shell 不同的 shell。这可能会破坏 VS Code 的远程服务器安装脚本，因此不建议这样做。相反，请使用更改远程计算机上的默认 shell。chsh

连接到为每个连接动态分配机器的系统

每次建立 SSH 连接时，某些系统都会动态地将 SSH 连接从集群路由到一个节点。这是 VS Code 的一个问题，因为它会建立两个连接来打开远程窗口：第一个连接用于安装或启动 VS Code 服务器（或查找已运行的实例），第二个用于创建 VS Code 使用的 SSH 端口隧道与服务器交谈。如果 VS Code 在创建第二个连接时路由到另一台计算机，则它将无法与 VS Code 服务器通信。

解决此问题的一种方法是使用ControlMasterOpenSSH 中的选项（仅限 macOS/Linux 客户端），如启用备用 SSH 身份验证方法中所述，以便 VS Code 的两个连接将通过到同一节点的单个 SSH 连接进行多路复用。

请联系您的系统管理员以获取配置帮助

SSH 是一种非常灵活的协议，支持多种配置。如果您在登录终端或远程 SSH输出窗口中看到其他错误，则可能是由于缺少设置造成的。

有关 SSH 主机和客户端所需设置的信息，请联系您的系统管理员。用于连接 SSH 主机的特定命令行参数可以添加到SSH 配置文件中。

要访问您的配置文件，请在命令面板 ( F1 )中运行Remote-SSH: Open Configuration File...。然后，您可以与管理员一起添加必要的设置。

启用备用 SSH 身份验证方法

如果您要连接到 SSH 远程主机并且是：

• 使用双因素身份验证连接
• 使用密码验证
• 当SSH 代理未运行或不可访问时，使用带有密码的 SSH 密钥

那么 VS Code 应该会自动提示您输入所需的信息。如果没有看到提示，请在 VS Code 中启用该remote.SSH.showLoginTerminal 设置。每当 VS Code 运行 SSH 命令时，此设置都会显示终端。然后，当终端出现时，您可以输入您的身份验证码、密码或密码。

如果仍然遇到问题，您可能需要添加以下属性并重settings.json试：

"remote.SSH.showLoginTerminal": true,
"remote.SSH.useLocalServer": false

如果您使用的是 macOS 和 Linux，并且想要减少输入密码或令牌的频率，您可以ControlMaster在本地计算机上启用该功能，以便 OpenSSH 通过单个连接运行多个 SSH 会话。

要启用ControlMaster：

1. 将如下条目添加到您的 SSH 配置文件中：

   Host *
       ControlMaster auto
       ControlPath  ~/.ssh/sockets/%r@%h-%p
       ControlPersist  600
   

2. 然后运行mkdir -p ~/.ssh/sockets创建sockets文件夹。

设置 SSH 代理

如果您使用带有密码的密钥连接到 SSH 主机，则应确保SSH 代理正在本地运行。VS Code 会自动将您的密钥添加到代理，因此您不必每次打开远程 VS Code 窗口时都输入密码。

要验证代理是否正在运行并且可以从 VS Code 环境访问，请ssh-add -l在本地 VS Code 窗口的终端中运行。您应该会看到代理中的密钥列表（或没有密钥的消息）。如果代理未运行，请按照以下说明启动它。启动代理后，请务必重新启动 VS Code。

视窗：

要在 Windows 上自动启用 SSH 代理，请启动本地管理员 PowerShell并运行以下命令：

# Make sure you're running as an Administrator
Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent
Get-Service ssh-agent

现在代理将在登录时自动启动。

Linux：

要在后台启动 SSH 代理，请运行：

eval "$(ssh-agent -s)"

要在登录时自动启动 SSH 代理，请将这些行添加到您的~/.bash_profile：

if [ -z "$SSH_AUTH_SOCK" ]; then
   # Check for a currently running instance of the agent
   RUNNING_AGENT="`ps -ax | grep 'ssh-agent -s' | grep -v grep | wc -l | tr -d '[:space:]'`"
   if [ "$RUNNING_AGENT" = "0" ]; then
        # Launch a new instance of the agent
        ssh-agent -s &> .ssh/ssh-agent
   fi
   eval `cat .ssh/ssh-agent`
fi

苹果系统：

默认情况下，代理应在 macOS 上运行。

使本地 SSH 代理在远程可用

本地计算机上的 SSH 代理允许远程 - SSH 扩展连接到您选择的远程系统，而无需重复提示输入密码，但在远程运行的 Git 等工具无法访问您本地解锁的私钥。

您可以通过打开遥控器上的集成终端并运行来看到这一点ssh-add -l。该命令应列出已解锁的密钥，但会报告有关无法连接到身份验证代理的错误。设置ForwardAgent yes使本地SSH Agent在远程环境中可用，解决了这个问题。

您可以通过编辑.ssh/config文件（或任何Remote.SSH.configFile设置 - 使用Remote-SSH: Open SSH Configuration File...命令来确保）并添加：

Host *
    ForwardAgent yes

请注意，您可能希望更具限制性，并且只为特定的命名主机设置选项。

修复 SSH 文件权限错误

SSH 对文件权限可能很严格，如果设置不正确，您可能会看到诸如“警告：未受保护的私钥文件！”之类的错误。有多种方法可以更新文件权限来解决此问题，下面各节将对此进行介绍。

本地 SSH 文件和文件夹权限

macOS / Linux：

在本地计算机上，确保设置以下权限：

文件夹/文件	权限
.ssh in your user folder	chmod 700 ~/.ssh
.ssh/config in your user folder	chmod 600 ~/.ssh/config
.ssh/id_ed25519.pub in your user folder	chmod 600 ~/.ssh/id_ed25519.pub
Any other key file	chmod 600 /path/to/key/file

视窗：

具体的预期权限可能会有所不同，具体取决于您使用的具体 SSH 实现。我们建议使用现成的Windows 10 OpenSSH 客户端。

在这种情况下，请确保.sshSSH 主机上远程用户的文件夹中的所有文件均归您所有，并且其他用户无权访问它。有关详细信息，请参阅Windows OpenSSH wiki。

对于所有其他客户，请查阅客户的文档以了解实施的预期。

服务器 SSH 文件和文件夹权限

macOS / Linux：

在您要连接的远程计算机上，确保设置了以下权限：

文件夹/文件	Linux/macOS 权限
.ssh in your user folder on the server	chmod 700 ~/.ssh
.ssh/authorized_keys in your user folder on the server	chmod 600 ~/.ssh/authorized_keys

请注意，目前仅支持 Linux 主机，因此省略了 macOS 和 Windows 10 的权限。

视窗：

有关为 Windows OpenSSH 服务器设置适当文件权限的详细信息，请参阅Windows OpenSSH wiki 。

安装支持的 SSH 客户端

操作系统	指示
Windows 10 1803+ / Server 2016/2019 1803+	安装Windows OpenSSH 客户端。
Earlier Windows	安装适用于 Windows 的 Git。
macOS	已预安装。
Debian/Ubuntu	跑步sudo apt-get install openssh-client
RHEL / Fedora / CentOS	跑步sudo yum install openssh-clients

sshVS Code 将在 PATH 中查找命令。ssh.exe如果失败，在 Windows 上它将尝试在 Windows 的默认 Git 安装路径中查找。您还可以通过将属性添加remote.SSH.path到settings.json.

安装受支持的 SSH 服务器

操作系统	指示	细节
Debian 8+ / Ubuntu 16.04+	跑步sudo apt-get install openssh-server	有关详细信息，请参阅Ubuntu SSH文档。
RHEL / CentOS 7+	跑步sudo yum install openssh-server && sudo systemctl start sshd.service && sudo systemctl enable sshd.service	有关详细信息，请参阅RedHat SSH文档。
SuSE 12+ / openSUSE 42.3+	在 Yast 中，转到服务管理器，在列表中选择“sshd”，然后单击启用。接下来转到防火墙，选择永久配置，然后在服务下检查sshd。	有关详细信息，请参阅SuSE SSH文档。
Windows 10 1803+ / Server 2016/2019 1803+	安装Windows OpenSSH 服务器。
macOS 10.14+ (Mojave)	启用远程登录。

解决在 SSH 主机上执行 Git 推送或同步时的挂起问题

如果使用 SSH 克隆 Git 存储库并且 SSH 密钥有密码，则 VS Code 的拉取和同步功能可能会在远程运行时挂起。

使用不带密码的 SSH 密钥、使用 HTTPS 克隆或git push从命令行运行来解决该问题。

使用 SSHFS 访问远程主机上的文件

SSHFS是一种基于 SFTP 构建的安全远程文件系统访问协议。它比 CIFS/Samba 共享等方式具有优势，因为只需通过 SSH 访问计算机即可。

注意：出于性能原因，SSHFS 最适合用于单个文件编辑和上传/下载内容。如果您需要使用一次批量读取/写入多个文件的应用程序（例如本地源代码控制工具），rsync是更好的选择。

macOS/Linux：

在 Linux 上，您可以使用发行版的包管理器来安装 SSHFS。对于 Debian/Ubuntu：sudo apt-get install sshfs

注意： WSL 1 不支持 FUSE 或 SSHFS，因此当前 Windows 的说明有所不同。WSL 2 确实包含 FUSE 和 SSHFS 支持，因此这很快就会改变。

在 macOS 上，您可以使用Homebrew安装 SSHFS ：

brew install --cask macfuse
brew install gromgit/fuse/sshfs-mac
brew link --overwrite sshfs-mac

此外，如果您不想使用命令行挂载远程文件系统，还可以安装SSHFS GUI。

要使用命令行，请从本地终端运行以下命令（替换user@hostname为远程用户和主机名/IP）：

export USER_AT_HOST=user@hostname
# Make the directory where the remote filesystem will be mounted
mkdir -p "$HOME/sshfs/$USER_AT_HOST"
# Mount the remote filesystem
sshfs "$USER_AT_HOST:" "$HOME/sshfs/$USER_AT_HOST" -ovolname="$USER_AT_HOST" -p 22  \
    -o workaround=nonodelay -o transform_symlinks -o idmap=user  -C

这将使远程计算机上的主文件夹在~/sshfs. 完成后，您可以使用操作系统的 Finder/文件资源管理器或使用命令行卸载它：

umount "$HOME/sshfs/$USER_AT_HOST"

视窗：

按着这些次序：

1. 在 Linux 上，将.gitattributes文件添加到项目中以强制 Linux 和 Windows 之间的行结尾一致，以避免由于两个操作系统之间的 CRLF/LF 差异而导致意外问题。有关详细信息，请参阅解决 Git 行结束问题。

2. 接下来，使用Chocolatey安装SSHFS-Win：choco install sshfs

3. 安装适用于 Windows 的 SSHFS 后，您可以使用文件资源管理器的映射网络驱动器...选项以及路径\\sshfs\user@hostname，其中user@hostname是您的远程用户和主机名/IP。您可以使用命令提示符编写脚本，如下所示：net use /PERSISTENT:NO X: \\sshfs\user@hostname

4. 完成后，通过右键单击文件资源管理器中的驱动器并选择“断开连接”来断开连接。

从终端连接到远程主机

配置主机后，您可以通过传递远程 URI 直接从终端连接到该主机。

例如，要连接remote_server并打开该/code/my_project文件夹，请运行：

code --remote ssh-remote+remote_server /code/my_project

我们需要猜测输入路径是文件还是文件夹。如果它有文件扩展名，则将其视为文件。

要强制打开文件夹，请在路径中添加斜杠或使用：

code --folder-uri vscode-remote://ssh-remote+remote_server/code/folder.with.dot

要强制打开文件，请添加--goto或使用：

code --file-uri vscode-remote://ssh-remote+remote_server/code/fileWithoutExtension

使用 rsync 维护源代码的本地副本

使用 SSHFS 访问远程文件的另一种方法是将rsync远程主机上文件夹的全部内容复制到本地计算机。该rsync命令将在每次运行时确定哪些文件需要更新，这比使用 或 之类的东西要高效和方便scp得多sftp。如果您确实需要使用多文件或性能密集型本地工具，那么这主要是需要考虑的事情。

该rsync命令在 macOS 上开箱即用，并且可以使用 Linux 包管理器（例如sudo apt-get install rsync在 Debian/Ubuntu 上）安装。对于 Windows，您需要使用WSL或Cygwin来访问该命令。

要使用该命令，请导航到要存储同步内容的文件夹，然后运行以下命令，替换user@hostname为远程用户和主机名/IP 以及/remote/source/code/path远程源代码位置。

在macOS、Linux 或 WSL 内部：

rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" .

或者在 Windows 上通过 PowerShell 使用WSL：

wsl rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" "`$(wslpath -a '$PWD')"

每次您想要获取文件的最新副本时，您都可以重新运行此命令，并且只会传输更新。出于性能原因，有意排除该.git文件夹，因此您可以使用本地 Git 工具，而不必担心远程主机上的状态。

要推送内容，请颠倒命令中的源参数和目标参数。但是，在 Windows 上，您应该.gitattributes在项目中添加一个文件，以强制行尾一致，然后再执行此操作。有关详细信息，请参阅解决 Git 行结束问题。

rsync -rlptzv --progress --delete --exclude=.git . "user@hostname:/remote/source/code/path"

清理远程上的 VS Code 服务器

SSH 扩展提供了用于从远程计算机清理 VS Code 服务器的命令，Remote-SSH：从主机卸载 VS Code 服务器...。该命令执行两件事：终止所有正在运行的 VS Code Server 进程并删除安装服务器的文件夹。

如果您想手动运行这些步骤，或者该命令不适合您，您可以运行如下脚本：

# Kill server processes
kill -9 $(ps aux | grep vscode-server | grep $USER | grep -v grep | awk '{print $2}')
# Delete related files and folder
rm -rf $HOME/.vscode-server # Or ~/.vscode-server-insiders

VS Code 服务器之前安装在下面，~/.vscode-remote因此您也可以检查该位置。

通过 SSH 连接到远程 WSL 2 主机

您可能想要使用 SSH 连接到远程计算机上运行的 WSL 发行版。查看本指南，了解如何从外部计算机通过 SSH 连接到 Windows 10 上的 Bash 和 WSL 2。

Dev Containers 技巧

如果您想了解有关使用 Dev Containers 的提示，可以转到 Dev Containers提示和技巧。

WSL 提示

首次启动：VS Code Server 先决条件

某些 WSL Linux 发行版缺少 VS Code 服务器启动所需的库。您可以使用包管理器将其他库添加到 Linux 发行版中。

Debian 和 Ubuntu

打开 Debian 或 Ubuntu WSL shell 以添加wget和ca-certificates：

sudo apt-get update && sudo apt-get install wget ca-certificates

阿尔卑斯山

以 root ( ) 身份打开 Alpine WSL shellwsl -d Alpine -u root以添加libstdc++：

apk update && apk add libstdc++

在 Windows 10 April 2018 Update（内部版本 1803）及更早版本上，/bin/bash需要：

apk update && apk add bash

选择 WSL 扩展使用的发行版

WSL：新窗口将打开默认注册的 WSL 发行版。

要打开非默认发行版，请code .从发行版的 WSL shell 运行以使用或使用WSL: New Window using Distro。

对于早于 Windows 10 2019 年 5 月更新（版本 1903）的 WSL 版本，WSL 命令只能使用默认发行版. 因此，WSL 扩展可能会提示您是否同意更改默认发行版。

您始终可以使用wslconfig.exe更改默认设置。

例如：

wslconfig /setdefault Ubuntu

您可以通过运行以下命令查看已安装的发行版：

wslconfig /l

配置服务器启动环境

当 WSL 扩展在 WSL 中启动 VS Code 服务器时，它不会运行任何 shell 配置脚本。这样做是为了避免自定义配置脚本阻止启动。

如果需要配置启动环境，可以使用此处所述的环境设置脚本。

配置远程分机主机环境

远程扩展主机和终端的环境基于默认 shell 的配置脚本。为了评估远程扩展主机进程的环境变量，服务器创建默认 shell 的实例作为交互式登录 shell。它从中探测环境变量并将它们用作远程扩展主机进程的初始环境。因此，环境变量的值取决于默认配置的 shell 以及该 shell 的配置脚本的内容。

有关每个 shell 配置脚本的概述，请参阅Unix shell 初始化。大多数 WSL 发行版已/bin/bash配置为默认 shell。/bin/bash将在第一个下查找启动文件，并在, ,下/etc/profile查找任何启动文件。~/.bash_profile~/.bash_login~/.profile

要更改 WSL 发行版的默认 shell，请按照此博客文章的说明进行操作。

修复代码命令不起作用的问题

如果由于无法找到而code从 Window 上的 WSL 终端输入不起作用，则您可能在 WSL 的 PATH 中丢失了一些关键位置。code

通过打开 WSL 终端并键入 进行检查echo $PATH。您应该会看到列出的 VS Code 安装路径。默认情况下，这将是：

/mnt/c/Users/Your Username/AppData/Local/Programs/Microsoft VS Code/bin

但是，如果您使用系统安装程序，安装路径为：

/mnt/c/Program Files/Microsoft VS Code/bin

...或者...

/mnt/c/Program Files (x86)/Microsoft VS Code/bin

WSL 的一个特性是路径继承自 Windows 中的 PATH 变量。要更改 Windows PATH 变量，请使用Windows 开始菜单中的编辑帐户命令的环境变量。

如果您已禁用路径共享功能，请编辑您的.bashrc，添加以下内容，然后启动一个新终端：

WINDOWS_USERNAME="Your Windows Alias"

export PATH="$PATH:/mnt/c/Windows/System32:/mnt/c/Users/${WINDOWS_USERNAME}/AppData/Local/Programs/Microsoft VS Code/bin"
# or...
# export PATH="$PATH:/mnt/c/Program Files/Microsoft VS Code/bin"
# or...
# export PATH="$PATH:/mnt/c/Program Files (x86)/Microsoft VS Code/bin"

注意：请务必在目录名称中引用或转义空格字符。

查找“code”命令的问题

如果code从 Windows 命令提示符键入无法启动 VS Code，您可以通过运行来帮助我们诊断问题VSCODE_WSL_DEBUG_INFO=true code .。

请提出问题并附上完整的输出。

查找启动或连接到服务器的问题

当 WSL 窗口无法连接到远程服务器时，您可以在 WSL 日志中获取更多信息。提交问题时，务必发送 WSL 日志的完整内容。

通过运行命令WSL: Open Log打开 WSL 日志。该日志将显示在 WSL 选项卡下的终端视图中。

remote.WSL.debug要获得更详细的日志记录，请在用户设置中启用该设置。

服务器因分段错误而无法启动

您可以通过向我们发送核心转储文件来帮助我们调查此问题。要获取核心转储文件，请执行以下步骤：

在 Windows 命令提示符中：

• 运行code --locate-extension ms-vscode-remote.remote-wsl以确定 WSL 扩展文件夹。
• cd到返回的路径。
• wslServer.sh使用 VS Code打开脚本， code .\scripts\wslServer.sh.
• 在最后一行之前（在 之前"$VSCODE_REMOTE_BIN/$COMMIT/bin/$SERVER_APPNAME" "$@"），添加 ulimit -C unlimited.
• 启动运行远程服务器的 WSL 窗口并等待分段错误。

核心文件将位于上面的 WSL 扩展文件夹中。

我在尝试重命名打开的工作区中的文件夹时看到 EACCES：权限被拒绝错误

这是 WSL 文件系统实现（Microsoft/WSL#3395、Microsoft/WSL#1956）的一个已知问题，由 VS Code 激活的文件观察器引起。该问题只会在 WSL 2 中得到解决。

为避免此问题，请设置remote.WSL.fileWatcher.polling为 true。但是，基于轮询会对大型工作区的性能产生影响。

对于大型工作区，您可能需要增加轮询间隔 ，remote.WSL.fileWatcher.pollingInterval并控制使用 监视的文件夹files.watcherExclude。

WSL 2不存在该文件监视程序问题，并且不受新设置的影响。

解决 WSL 中的 Git 行结束问题（导致许多文件被修改）

由于 Windows 和 Linux 使用不同的默认行结尾，Git 可能会报告大量已修改的文件，这些文件除了行结尾之外没有任何差异。.gitattributes为了防止这种情况发生，您可以使用文件或在 Windows 端全局禁用行结束转换。

通常，在存储库中添加或修改 .gitattributes文件是解决此问题的最可靠方法。将此文件提交到源代码管理将对其他人有所帮助，并允许您根据需要通过存储库改变行为。例如，将以下内容添加.gitattributes到存储库的根目录中将强制所有内容均为 LF，但需要 CRLF 的 Windows 批处理文件除外：

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

请注意，这适用于Git v2.10+，因此如果您遇到问题，请确保您安装了最新的 Git 客户端。您可以将需要 CRLF 的其他文件类型添加到同一文件中。

如果您仍希望始终上传 Unix 风格的行结尾 (LF)，则可以使用该input选项。

git config --global core.autocrlf input

如果您希望完全禁用行结束转换，请运行以下命令：

git config --global core.autocrlf false

最后，您可能需要再次克隆存储库才能使这些设置生效。

在 Windows 和 WSL 之间共享 Git 凭据

如果您使用 HTTPS 克隆存储库并在 Windows 中配置了凭据帮助程序，则可以与 WSL 共享此信息，以便您输入的密码在双方都保留。（请注意，这不适用于使用 SSH 密钥。）

只需按照以下步骤操作：

1. 通过在Windows 命令提示符或PowerShell中运行以下命令，在 Windows 上配置凭据管理器：

    git config --global credential.helper wincred
   

2. 配置 WSL 以使用相同的凭据帮助程序，但在WSL 终端中运行以下命令：

    git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager-core.exe"
   

现在，WSL 可以使用您在 Windows 端使用 Git 时输入的任何密码，反之亦然。

解决从 WSL 进行 Git 推送或同步时的挂起问题

如果使用 SSH 克隆 Git 存储库并且 SSH 密钥有密码，则 VS Code 的拉取和同步功能可能会在远程运行时挂起。

使用不带密码的 SSH 密钥、使用 HTTPS 克隆或git push从命令行运行来解决该问题。

GitHub Codespaces 提示

有关GitHub Codespaces的提示和问题，请参阅GitHub Codespaces 文档。您还可以查看可能影响您的 Codespace 的已知 Web 限制和调整。

扩展提示

虽然许多扩展无需修改即可工作，但存在一些问题可能会阻止某些功能按预期工作。在某些情况下，您可以使用另一个命令来解决该问题，而在其他情况下，可能需要修改扩展。本部分提供常见问题的快速参考以及解决这些问题的技巧。您还可以参阅有关支持远程开发的主要扩展文章，以获取有关修改扩展以支持远程扩展主机的深入指南。

解决有关缺少依赖项的错误

某些扩展依赖于某些 WSL Linux 发行版的基本安装中未找到的库。您可以使用包管理器将其他库添加到 Linux 发行版中。对于基于 Ubuntu 和 Debian 的发行版，运行sudo apt-get install <package>以安装所需的库。检查错误消息中提到的扩展或运行时的文档，了解其他安装详细信息。

远程应用时本地绝对路径设置失败

当您连接到远程端点时，将重用 VS Code 的本地用户设置。虽然这可以保持用户体验一致，但您可能需要更改本地计算机与每个主机/容器/WSL 之间的绝对路径设置，因为目标位置不同。

解决方案：连接到远程端点后，您可以通过运行命令选项板 ( F1 ) 中的首选项：打开远程设置命令或通过选择设置编辑器中的远程选项卡来设置端点特定的设置。每当您连接时，这些设置都会覆盖您已有的任何本地设置。

需要在远程端点上安装本地 VSIX

有时，您想要在远程计算机上安装本地 VSIX，无论是在开发过程中还是在扩展作者要求您尝试修复时。

解决方案：连接到 SSH 主机、容器或 WSL 后，您可以像在本地一样安装 VSIX。从命令面板 ( F1 )运行扩展：从 VSIX 安装...命令。您可能还需要添加以防止自动更新到最新的 Marketplace 版本。有关在远程环境中开发和测试扩展的更多信息，请参阅支持远程开发。"extensions.autoUpdate": falsesettings.json

浏览器本地打不开

某些扩展使用外部节点模块或自定义代码来启动浏览器窗口。不幸的是，这可能会导致扩展程序远程而不是本地启动浏览器。

解决方案：扩展程序可以使用vscode.env.openExternalAPI 来解决此问题。有关详细信息，请参阅扩展作者指南。

剪贴板不起作用

一些扩展使用节点模块，例如clipboardy与剪贴板集成。不幸的是，这可能会导致扩展与远程端的剪贴板错误集成。

解决方案：扩展可以切换到 VS Code 剪贴板 API 来解决该问题。有关详细信息，请参阅扩展作者指南。

无法从浏览器或应用程序访问本地 Web 服务器

在容器、SSH 主机或通过 GitHub Codespaces 内部工作时，浏览器连接的端口可能会被阻止。

解决方案：扩展可以使用vscode.env.openExternal或vscode.env.asExternalUriAPI（自动转发本地主机端口）来解决此问题。有关详细信息，请参阅扩展作者指南。作为解决方法，请使用“转发端口”命令手动执行此操作。

Webview内容不出现

如果扩展程序的 webview 内容使用iframe连接到本地 Web 服务器，则 webview 连接到的端口可能会被阻止。此外，如果扩展程序硬编码vscode-resource://URI 而不是使用asWebviewUri，内容可能不会出现在 Codespaces 浏览器编辑器中。

解决方案：扩展程序可以使用webview.asWebviewUri来解决vscode-resource://URI 问题。

如果端口被阻止，最好的方法是使用webview 消息传递API。作为解决方法，vscode.env.asExternalUri 可以使用允许 Web 视图从 VS Code 连接到生成的本地主机 Web 服务器。但是，目前MicrosoftDocs/vscodespaces#11已（仅）针对基于浏览器的 Codespaces 编辑器阻止了此操作。有关解决方法的详细信息，请参阅扩展作者指南。

阻止本地主机端口

如果您尝试从外部应用程序连接到本地主机端口，该端口可能会被阻止。

解决方案： VS Code 1.40 引入了一个新的vscode.env.asExternalUriAPI，用于扩展以编程方式转发任意端口。有关详细信息，请参阅扩展作者指南。作为解决方法，您可以使用“转发端口”命令手动执行此操作。

存储扩展数据时出错

扩展可能会尝试通过查找~/.config/CodeLinux 上的文件夹来保留全局数据。该文件夹可能不存在，这可能会导致扩展抛出诸如ENOENT: no such file or directory, open '/root/.config/Code/User/filename-goes-here.

解决方案：扩展可以使用context.globalStorageUri或context.storageUri属性来解决此问题。有关详细信息，请参阅扩展作者指南。

无法登录/每次连接到新端点时都必须登录

需要登录的扩展可能会使用自己的代码来保存机密。此代码可能会由于缺少依赖项而失败。即使成功，机密也将远程存储，这意味着您必须登录每个新端点。

解决方案：扩展可以使用SecretStorage API来解决此问题。有关详细信息，请参阅扩展作者指南。

不兼容的扩展阻止 VS Code 连接

如果远程主机、容器或 WSL 中安装了不兼容的扩展，我们就会看到 VS Code 服务器由于不兼容而挂起或崩溃的情况。如果扩展程序立即激活，这可能会阻止您连接并卸载该扩展程序。

解决方案：按照以下步骤手动删除远程扩展文件夹：

1. 对于容器，请确保devcontainer.json不再包含对错误扩展的引用。

2. 接下来，使用单独的终端/命令提示符连接到远程主机、容器或 WSL。

   • 如果是 SSH 或 WSL，请相应地连接到环境（运行ssh以连接到服务器或打开 WSL 终端）。
   • docker ps -a如果使用容器，请通过调用并在列表中查找具有正确名称的图像来识别容器 ID 。如果容器已停止，请运行docker run -it <id> /bin/sh. 如果正在运行，则运行docker exec -it <id> /bin/sh.

3. 连接后，运行rm -rf ~/.vscode-server/extensionsVS Code stable 和/或rm -rf ~/.vscode-server-insiders/extensionsVS Code Insiders 以删除所有扩展。

交付或获取预构建本机模块的扩展失败

与 VS Code 扩展捆绑（或动态获取）的本机模块必须使用 Electron 的electron-rebuild. 但是，VS Code Server 运行标准（非 Electron）版本的 Node.js，这可能会导致二进制文件在远程使用时失败。

解决方案：需要修改扩展来解决此问题。他们需要包含（或动态获取）VS Code 附带的 Node.js 中“模块”版本的两组二进制文件（Electron 和标准 Node.js），然后检查是否在其激活函数中context.executionContext === vscode.ExtensionExecutionContext.Remote设置正确的二进制文件。有关详细信息，请参阅扩展作者指南。

扩展仅在非 x86_64 主机或 Alpine Linux 上失败

如果扩展在 Debian 9+、Ubuntu 16.04+ 或 RHEL/CentOS 7+ 远程 SSH 主机、容器或 WSL 上运行，但在受支持的非 x86_64 主机（例如 ARMv7l）或 Alpine Linux 容器上失败，则该扩展可能会仅包含不支持这些平台的本机代码或运行时。例如，扩展可能仅包括本机模块或运行时的 x86_64 编译版本。对于 Alpine Linux，由于Alpine Linux ( ) 和其他发行版 ( )的实现方式存在根本差异，所包含的本机代码或运行时可能无法工作。libcmuslglibc

解决方案： 扩展需要通过编译/包含这些附加目标的二进制文件来选择支持这些平台。需要注意的是，某些第三方 npm 模块也可能包含可能导致此问题的本机代码。因此，在某些情况下，您可能需要与 npm 模块作者合作来添加其他编译目标。有关详细信息，请参阅扩展作者指南。

由于缺少模块而导致扩展失败

依赖于 Electron 或 VS Code 基本模块（未由扩展 API 公开）而不提供回退的扩展在远程运行时可能会失败。您可能会在开发人员工具控制台中看到错误，例如original-fs找不到。

解决方案：删除对 Electron 模块的依赖或提供后备。有关详细信息，请参阅扩展作者指南。

无法访问远程工作区文件/将其传输到本地计算机

在外部应用程序中打开工作区文件的扩展可能会遇到错误，因为外部应用程序无法直接访问远程文件。

解决方案：如果您创建一个设计为在本地运行的“UI”扩展，则可以使用vscode.workspace.fsAPI 与远程工作区文件系统进行交互。然后，您可以将其作为“工作区”扩展的依赖项，并根据需要使用命令调用它。有关不同类型的扩展以及如何使用命令在它们之间进行通信的详细信息，请参阅扩展作者指南。

无法从分机访问连接的设备

访问本地连接设备的扩展在远程运行时将无法连接到它们。

解决方案：目前无。我们正在研究解决这个问题的最佳方法。

问题和反馈

报告问题

如果您遇到远程开发扩展之一的问题，收集正确的日志非常重要，以便我们能够帮助诊断您的问题。

每个远程分机都有一个查看其日志的命令。

您可以使用 Remote -SSH: Show Log从命令面板 ( F1 ) 获取远程 - SSH 扩展日志。报告远程 - SSH 问题时，还请验证您是否能够从外部终端通过 SSH 连接到您的计算机（不使用远程 - SSH）。

同样，您可以使用Dev Containers: Show Container Log获取 Dev Containers 扩展日志。

与上面两个一样，您可以使用WSL: Show Log获取 WSL 扩展日志。另请检查WSL 存储库中的上游是否正在跟踪您的问题（并且不是由于 WSL 扩展造成的）。

如果您在远程使用其他扩展时遇到问题（例如，其他扩展未在远程上下文中正确加载或安装），从远程扩展主机输出通道获取日志会很有帮助（输出：关注输出视图） ，然后从下拉列表中选择日志（远程分机主机） 。

注意：如果您只看到日志（分机主机），则这是本地分机主机，远程分机主机未启动。这是因为日志通道仅在创建日志文件后创建，因此如果远程扩展主机未启动，则远程扩展主机日志文件不会创建，也不会显示在输出视图中。这仍然是包含在您的问题中的有用信息。

远程问题和反馈资源

我们还有各种其他远程资源：

• 请参阅远程开发常见问题解答。
• 在堆栈溢出上搜索。
• 添加功能请求或报告问题。