远程开发的技巧和窍门

本文涵盖了针对每个Visual Studio Code 远程开发扩展的故障排除技巧和窍门。有关设置和使用每个特定扩展的详细信息，请参阅SSH、容器和WSL文章。或者尝试入门教程，以帮助您在远程环境中快速运行。

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

SSH 提示

SSH功能强大且灵活，但这也增加了一些设置的复杂性。本节包括一些在不同环境中启动和运行Remote - SSH扩展的技巧和窍门。

配置 $EDITOR 变量

对于macOS / Linux远程主机，将此代码片段添加到您的shell配置文件中（如.bashrc或.zshrc）

if [ "$VSCODE_INJECTION" = "1" ]; then
    export EDITOR="code --wait" # or 'code-insiders' if you're using VS Code Insiders
fi

对于Windows主机，以下是等效的Powershell：

if ($env:VSCODE_INJECTION -eq "1") {
    $env:EDITOR = "code --wait"  # or 'code-insiders' for VS Code Insiders
}

现在运行一个使用 $EDITOR 变量的终端命令，比如 git commit，将会在 VS Code 中打开文件，而不是默认的基于终端的编辑器（如 vim 或 nano）。

配置基于密钥的认证

SSH公钥认证是一种方便且高安全性的认证方法，它将本地的“私钥”与您在SSH主机上的用户账户关联的“公钥”结合起来。本节将指导您如何生成这些密钥并将其添加到主机。

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

快速开始：使用SSH密钥

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

创建您的本地SSH密钥对

检查您是否已经在本地机器上拥有SSH密钥。这通常位于macOS / Linux上的~/.ssh/id_ed25519.pub，以及Windows上用户配置文件文件夹中的.ssh目录（例如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 <username>: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主机：

  • 主机使用OpenSSH服务器，用户属于管理员组：

    export USER_AT_HOST="your-user-name-on-host@hostname"
    export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
    
    ssh $USER_AT_HOST "powershell Add-Content -Force -Path \"\$Env:PROGRAMDATA\\ssh\\administrators_authorized_keys\" -Value '$(tr -d '\n\r' < "$PUBKEYPATH")'"
    

  • 否则：

    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主机上远程用户的.ssh文件夹中的authorized_keys文件是否归您所有，并且没有其他用户有权访问它。详情请参阅OpenSSH wiki。

授权您的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主机：

  • 主机使用OpenSSH服务器，用户属于管理员组：

    $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 `"Add-Content -Force -Path `"`$Env:PROGRAMDATA\ssh\administrators_authorized_keys`" `""
    

  • 否则：

    $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主机上远程用户的.ssh文件夹中的authorized_keys文件是否归您所有，并且没有其他用户有权访问它。详情请参阅OpenSSH wiki。

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

虽然在所有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 中，在命令面板（F1）中运行 Remote-SSH: Open Configuration File...，选择一个 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 中，在命令面板（F1）中运行 Remote-SSH: Open Configuration File...，选择你想要更改的 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
   

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

Remote - SSH 扩展安装并维护 "VS Code Server"。服务器启动时会生成一个随机密钥，任何新连接到服务器的请求都需要提供该密钥。该密钥存储在远程磁盘上，仅当前用户可读。有一个 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来进入套接字模式。

   

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

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

1. 在SSH主机上（不是本地），用文本编辑器（如vi、nano或pico）打开/etc/ssh/sshd_config。
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服务器中。

幸运的是，你可以通过在settings.json中添加以下内容来特别告诉VS Code你的SSH主机是否运行Windows，从而解决这个问题：

"remote.SSH.useLocalServer": false

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

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

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

在远程主机上启用TCP转发

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

open failed: administratively prohibited: open failed

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

1. 在SSH主机上（非本地），使用文本编辑器（如Vim、nano、Pico或Notepad）打开/etc/ssh/sshd_config或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文章以了解其使用示例。

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

远程机器必须能够访问互联网，以便能够从市场下载VS Code服务器和扩展。有关连接要求的详细信息，请参阅FAQ。

在远程主机上设置 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

一些用户从他们的.bash_profile或其他启动脚本中启动不同的shell，因为他们希望使用不同于默认的shell。这可能会破坏VS Code的远程服务器安装脚本，因此不推荐这样做。相反，使用chsh来更改远程机器上的默认shell。

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

一些系统会在每次建立SSH连接时，动态地将SSH连接路由到集群中的一个节点。这对于VS Code来说是一个问题，因为它需要建立两个连接来打开一个远程窗口：第一个连接用于安装或启动VS Code服务器（或查找已经运行的实例），第二个连接用于创建VS Code用来与服务器通信的SSH端口隧道。如果VS Code在创建第二个连接时被路由到不同的机器，它将无法与VS Code服务器通信。

解决这个问题的一个方法是使用OpenSSH中的ControlMaster选项（仅限macOS/Linux客户端），如启用替代SSH认证方法中所述，这样VS Code的两个连接将通过单个SSH连接到同一节点进行多路复用。

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

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

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

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

启用替代的SSH认证方法

如果您正在连接到SSH远程主机并且满足以下任一条件：

• 使用双因素认证进行连接
• 使用密码认证
• 当SSH Agent未运行或无法访问时，使用带有密码的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的环境中访问，请在本地VS Code窗口的终端中运行ssh-add -l。您应该会看到代理中的密钥列表（或一条消息，表示它没有密钥）。如果代理没有运行，请按照这些说明启动它。启动代理后，请确保重新启动VS Code。

Windows:

要在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:

代理程序默认应在macOS上运行。

使本地SSH代理在远程可用

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

你可以通过在远程打开集成终端并运行ssh-add -l来看到这一点。该命令应该列出未锁定的密钥，但会报告一个关于无法连接到认证代理的错误。设置ForwardAgent yes使得本地SSH代理在远程环境中可用，从而解决了这个问题。

你可以通过编辑你的.ssh/config文件（或者Remote.SSH.configFile设置的文件 - 使用Remote-SSH: 打开SSH配置文件...命令来确认）并添加以下内容来实现：

Host *
    ForwardAgent yes

请注意，您可能希望更加严格，仅针对特定的命名主机设置此选项。

修复SSH文件权限错误

SSH 对文件权限要求严格，如果设置不正确，您可能会看到诸如“警告：未受保护的私钥文件！”之类的错误。有几种方法可以更新文件权限以解决此问题，这些方法将在以下部分中描述。

本地SSH文件和文件夹权限

macOS / Linux:

在您的本地机器上，请确保设置了以下权限：

Windows:

具体的预期权限可能会根据您使用的确切SSH实现而有所不同。我们建议使用开箱即用的Windows 10 OpenSSH Client。

在这种情况下，请确保SSH主机上远程用户的.ssh文件夹中的所有文件都由您拥有，并且没有其他用户有权访问它。详情请参阅Windows OpenSSH wiki。

对于所有其他客户端，请查阅您的客户端文档以了解实现期望的内容。

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

macOS / Linux:

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

请注意，目前仅支持Linux主机，这就是为什么省略了macOS和Windows 10的权限。

Windows:

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

安装支持的SSH客户端

VS Code 将在 PATH 中查找 ssh 命令。如果找不到，在 Windows 上它将尝试在默认的 Git for Windows 安装路径中查找 ssh.exe。您还可以通过将 remote.SSH.path 属性添加到 settings.json 来明确告诉 VS Code 在哪里找到 SSH 客户端。

安装支持的SSH服务器

解决在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"

Windows:

按照以下步骤操作：

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

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

3. 一旦你安装了SSHFS for Windows，你可以使用文件资源管理器中的映射网络驱动器...选项，路径为\\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 包管理器安装（例如在 Debian/Ubuntu 上使用 sudo apt-get install rsync）。对于 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服务器进程，并删除服务器安装的文件夹。

如果你想手动运行这些步骤，或者命令对你不起作用，你可以运行一个像这样的脚本：

# 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。

提交问题

如果您在使用Remote-SSH扩展时遇到问题，并认为需要提交问题，请首先确保您已阅读本网站上的文档，然后查看故障排除维基文档，以获取有关获取日志文件和尝试更多步骤的信息，这些步骤可能有助于缩小问题的来源。

开发容器提示

如果您想阅读有关使用开发容器的提示，您可以前往开发容器的提示与技巧。

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

Alpine

以root身份打开Alpine WSL shell（wsl -d Alpine -u root）以添加libstdc++：

apk update && apk add libstdc++

在Windows 10 2018年4月更新（版本1803）及更早版本上，需要/bin/bash：

apk update && apk add bash

选择WSL扩展使用的发行版

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

要打开一个非默认的发行版，请从该发行版的WSL shell中运行code .或使用WSL: 使用发行版的新窗口。

对于早于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 的配置脚本内容。

请参阅Unix shell初始化以了解每个shell的配置脚本概述。大多数WSL发行版将/bin/bash配置为默认shell。/bin/bash将首先查找/etc/profile下的启动文件，以及~/.bash_profile、~/.bash_login、~/.profile下的任何启动文件。

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

解决代码命令无法工作的问题

如果在Windows上的WSL终端中键入code不起作用，因为找不到code，您可能在WSL的PATH中缺少一些关键位置。

通过打开一个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'命令查找问题

如果在Windows命令提示符下输入code没有启动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 到返回的路径。
• 使用VS Code打开wslServer.sh脚本，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中运行以下命令来配置凭据管理器：

    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"
   

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

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

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

要么使用没有密码的SSH密钥，要么使用HTTPS克隆，或者从命令行运行git push来解决这个问题。

GitHub Codespaces 提示

有关GitHub Codespaces的提示和问题，请参阅GitHub Codespaces文档。您还可以查看可能影响您的Codespaces的已知网络限制和适应。

扩展提示

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

解决关于缺失依赖项的错误

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

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

当您连接到远程端点时，VS Code 的本地用户设置会被重复使用。虽然这保持了用户体验的一致性，但由于目标位置不同，您可能需要在本地机器和每个主机/容器/WSL之间更改绝对路径设置。

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

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

有时你可能想在远程机器上安装一个本地的VSIX，无论是在开发过程中还是当扩展作者要求你尝试一个修复时。

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

浏览器无法在本地打开

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

解决方案： 该扩展可以使用 vscode.env.openExternal API 来解决此问题。详情请参阅 扩展作者指南。

剪贴板无法工作

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

解决方案： 该扩展可以切换到 VS Code 剪贴板 API 来解决此问题。详情请参阅 扩展作者指南。

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

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

解决方案：扩展可以使用vscode.env.openExternal或vscode.env.asExternalUri API（自动转发本地主机端口）来解决此问题。详情请参阅扩展作者指南。作为临时解决方案，可以使用转发端口命令手动执行此操作。

Webview内容未显示

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

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

如果端口被阻止，最好的方法是使用webview消息传递 API。作为一种变通方法，可以使用vscode.env.asExternalUri来允许webview从VS Code连接到生成的本地主机web服务器。然而，目前这在基于浏览器的Codespaces编辑器中（仅限）被MicrosoftDocs/vscodespaces#11阻止。有关变通方法的详细信息，请参阅扩展作者指南。

被阻止的本地主机端口

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

解决方案： VS Code 1.40 引入了一个新的 vscode.env.asExternalUri API，用于扩展程序以编程方式转发任意端口。详情请参阅 扩展作者指南。作为临时解决方案，您可以使用 转发端口 命令手动执行此操作。

存储扩展数据时出错

扩展程序可能会尝试通过在Linux上查找~/.config/Code文件夹来持久化全局数据。此文件夹可能不存在，这可能导致扩展程序抛出类似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。

   • If SSH or WSL, connect to the environment accordingly (run ssh to connect to the server or open WSL terminal).
   • If using a container, identify the container ID by calling docker ps -a and looking through the list for an image with the correct name. If the container is stopped, run docker run -it <id> /bin/sh. If it is running, run docker exec -it <id> /bin/sh.

3. 连接后，运行 rm -rf ~/.vscode-server/extensions 以删除 VS Code 稳定版的所有扩展，和/或运行 rm -rf ~/.vscode-server-insiders/extensions 以删除 VS Code Insiders 的所有扩展。

扩展程序在发布或获取预构建原生模块时失败

与VS Code扩展捆绑（或动态获取）的原生模块必须使用Electron的electron-rebuild重新编译。然而，VS Code服务器运行的是标准（非Electron）版本的Node.js，这可能导致在远程使用时二进制文件失败。

解决方案：需要修改扩展以解决此问题。它们需要包含（或动态获取）Node.js中VS Code附带的“模块”版本的两组二进制文件（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中的libc（musl）与其他发行版（glibc）的实现方式存在根本差异，包含的本机代码或运行时可能无法工作。

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

扩展因缺少模块而失败

依赖于Electron或VS Code基础模块（未通过扩展API暴露）且未提供回退方案的扩展在远程运行时可能会失败。您可能会在开发者工具控制台中看到类似original-fs未找到的错误。

解决方案： 移除对Electron模块的依赖或提供一个备用方案。详情请参阅扩展作者指南。

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

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

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

无法从扩展访问连接的设备

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

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

问题和反馈

报告问题

如果您在使用远程开发扩展时遇到问题，收集正确的日志非常重要，这样我们才能帮助诊断您的问题。

每个远程扩展都有一个命令来查看其日志。

您可以通过命令面板中的Remote-SSH: Show Log（F1）获取Remote - SSH扩展日志。在报告Remote - SSH问题时，请同时验证您是否能够从外部终端（不使用Remote - SSH）SSH到您的机器。

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

与上述两者类似，您可以使用WSL: 显示日志来获取WSL扩展日志。同时，请检查您的问题是否在WSL仓库中被跟踪（并且不是由于WSL扩展引起的）。

如果您在使用其他扩展程序时遇到问题（例如，其他扩展程序在远程环境中无法正确加载或安装），从远程扩展主机输出通道（输出：聚焦输出视图）获取日志，并从下拉菜单中选择日志（远程扩展主机）会很有帮助。

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

远程问题和反馈资源

我们提供各种其他远程资源：

• 参见 远程开发常见问题解答.
• 在Stack Overflow上搜索。
• 添加一个功能请求或报告问题。