远程开发技巧与提示

本文介绍了 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 主机上与您的用户帐户关联的“公钥”相结合。本节将引导您完成如何生成这些密钥并将它们添加到主机的过程。

提示： Windows 版 PuTTY 不是受支持的客户端，但您可以转换在 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: 打开配置文件...，选择一个 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. 从应用程序菜单中选择 Conversions > Export OpenSSH key（转换 > 导出 OpenSSH 密钥）。将转换后的密钥保存到本地位置，即用户配置文件文件夹中的 .ssh 目录下（例如 C:\Users\youruser\.ssh）。

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

4. 在 VS Code 中，在命令面板 (F1) 中运行 Remote-SSH: 打开配置文件...，选择您要更改的 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 处无需身份验证即可访问。

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

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

要进行配置：

1. 确保您的 Windows、macOS 或 Linux 上安装了本地 OpenSSH 6.7+ SSH 客户端，并且安装了 OpenSSH 6.7+ Linux 或 macOS 主机（Windows 不支持此模式）。

2. 通过在本地 VS Code 用户设置中启用 Remote.SSH: 远程服务器监听套接字，将 Remote - SSH 切换到套接字模式。

   

3. 如果您已连接到 SSH 主机，请从命令面板 (F1) 中选择 Remote-SSH: 终止主机上的 VS Code 服务器...，以便设置生效。

如果在连接时遇到错误，您可能需要在 SSH 主机的 sshd 配置上启用套接字转发。为此，请执行以下操作

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: 终止主机上的 VS Code 服务器。这将删除服务器，从而可以修复您可能看到的各种问题和错误消息，例如“无法建立与 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 转发

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 文章，以获取其用法的示例。

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

远程计算机必须可以访问互联网，才能从 Marketplace 下载 VS Code Server 和扩展。有关连接要求的详细信息，请参阅 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

解决以 noexec 挂载的 /tmp

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

检查安装期间是否启动了不同的 shell

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

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

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

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

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

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

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

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

启用备用 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 Agent

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

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

Windows

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

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

现在，agent 将在登录时自动启动。

Linux

要在后台启动 SSH Agent，请运行

eval "$(ssh-agent -s)"

要在登录时自动启动 SSH Agent，请将以下行添加到您的 ~/.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

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

使本地 SSH Agent 在远程可用

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

您可以通过打开远程集成终端并运行 ssh-add -l 来查看此情况。该命令应列出解锁的密钥，但实际上报告了有关无法连接到身份验证 agent 的错误。设置 ForwardAgent yes 使本地 SSH Agent 在远程环境中可用，从而解决了此问题。

您可以通过编辑您的 .ssh/config 文件（或 Remote.SSH.configFile 设置为的任何文件 - 使用 Remote-SSH: 打开 SSH 配置文件... 命令以确保）并添加

Host *
    ForwardAgent yes

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

修复 SSH 文件权限错误

SSH 对文件权限可能很严格，如果文件权限设置不正确，您可能会看到诸如“WARNING: UNPROTECTED PRIVATE KEY FILE!”之类的错误。有几种方法可以更新文件权限以修复此问题，这些方法在以下各节中进行了描述。

本地 SSH 文件和文件夹权限

macOS/Linux

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

Windows

具体的预期权限可能会因您正在使用的确切 SSH 实现而异。我们建议使用开箱即用的 Windows 10 OpenSSH 客户端。

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

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

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

macOS/Linux

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

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

Windows

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

安装受支持的 SSH 客户端

运行 sudo yum install openssh-clients

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

macOS 10.14+ (Mojave)

启用 远程登录。

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

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

可以使用没有密码的 SSH 密钥，使用 HTTPS 克隆，或从命令行运行 git push 来解决此问题。

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

macOS/Linux:

SSHFS 是一种安全的远程文件系统访问协议，它建立在 SFTP 的基础上。与 CIFS/Samba 共享之类的协议相比，它具有优势，因为它只需要对计算机进行 SSH 访问即可。

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

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

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

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

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

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

umount "$HOME/sshfs/$USER_AT_HOST"

Windows

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

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

2. 请按照以下步骤操作

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

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

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

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

从终端连接到远程主机

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

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

例如，要连接到 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 来访问该命令。

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

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

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

在 macOS、Linux 或 WSL 内部

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

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

清理远程计算机上的 VS Code Server

SSH 扩展提供了一个命令，用于从远程计算机清理 VS Code Server，即 Remote-SSH: Uninstall VS Code Server from Host...(Remote-SSH: 从主机卸载 VS Code Server...)。该命令执行两项操作：它会终止任何正在运行的 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 Server 之前安装在 ~/.vscode-remote 下，因此您也可以检查该位置。

SSH 进入远程 WSL 2 主机

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

提交 Issue

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

开发容器技巧

如果您想阅读有关使用开发容器的技巧，可以转到开发容器提示和技巧。

WSL 技巧

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

某些 WSL Linux 发行版缺少 VS Code Server 启动所需的库。您可以使用其软件包管理器将其他库添加到 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: New Window(WSL: 新建窗口) 将打开注册为默认的 WSL 发行版。

要打开非默认发行版，请从要使用的发行版的 WSL shell 运行 code .，或使用 WSL: New Window using Distro(WSL: 使用发行版新建窗口)。

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

您可以随时使用 wslconfig.exe 更改默认设置。

例如

wslconfig /setdefault Ubuntu

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

wslconfig /l

配置服务器启动的环境

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

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

配置远程扩展主机的环境

远程扩展主机和终端的环境基于默认 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 命令无法工作的问题

如果在 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 . 来帮助我们诊断问题。

请提交 Issue 并附上完整输出。

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

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

通过运行命令 WSL: Open Log(WSL: 打开日志) 打开 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 中运行以下命令，在 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.exe"
   

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

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

启用 远程登录。

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

GitHub Codespaces 技巧

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

扩展技巧

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

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

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

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

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

解决方法： 连接到远程终结点后，您可以通过从命令面板 (F1) 运行 Preferences: Open Remote Settings(首选项: 打开远程设置) 命令，或通过在设置编辑器中选择 Remote(远程) 选项卡来设置特定于终结点的设置。每当您连接时，这些设置将覆盖您已设置的任何本地设置。

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

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

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

浏览器未在本地打开

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

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

剪贴板不起作用

某些扩展程序使用诸如 clipboardy 之类的 node 模块来与剪贴板集成。不幸的是，这可能会导致扩展程序错误地与远程端的剪贴板集成。

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

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

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

解决方法： 扩展程序可以使用 vscode.env.openExternal 或 vscode.env.asExternalUri API（自动转发 localhost 端口）来解决此问题。有关详细信息，请参阅扩展程序作者指南。作为一种解决方法，请使用 Forward a Port(转发端口) 命令手动执行此操作。

Webview 内容未显示

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

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

如果端口被阻止，最好的方法是改为使用 webview 消息传递 API。作为一种解决方法，可以使用 vscode.env.asExternalUri 允许 webview 从 VS Code 连接到衍生的 localhost Web 服务器。但是，目前对于基于浏览器的 Codespaces 编辑器（仅限）被 MicrosoftDocs/vscodespaces#11 阻止。有关解决方法的详细信息，请参阅扩展程序作者指南。

localhost 端口被阻止

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

解决方法： VS Code 1.40 引入了一个新的 vscode.env.asExternalUri API，供扩展程序以编程方式转发任意端口。有关详细信息，请参阅扩展程序作者指南。作为一种解决方法，您可以使用 Forward a Port(转发端口) 命令手动执行此操作。

存储扩展程序数据时出错

扩展程序可能会尝试通过查找 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 Server 由于不兼容而挂起或崩溃的实例。如果扩展程序立即激活，这可能会阻止您连接并能够卸载扩展程序。

解决方法： 通过执行以下步骤手动删除远程扩展程序文件夹

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. 连接后，对于 VS Code 稳定版，运行 rm -rf ~/.vscode-server/extensions，对于 VS Code Insiders 版，运行 rm -rf ~/.vscode-server-insiders/extensions 以删除所有扩展程序。

随附或获取预构建本机模块的扩展程序失败

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

解决方法： 需要修改扩展程序以解决此问题。它们将需要包含（或动态获取）两组二进制文件（Electron 和标准 Node.js），用于 VS Code 附带的 Node.js 中的“modules”版本，然后检查其激活函数中是否 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 (musl) 和其他发行版 (glibc) 中 libc 的实现方式之间存在根本差异，因此包含的本机代码或运行时可能无法工作。

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

扩展程序由于缺少模块而失败

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

解决方法： 删除对 Electron 模块的依赖项或提供回退。有关详细信息，请参阅扩展程序作者指南。

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

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

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

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

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

解决方法： 目前没有。我们正在调查解决此问题的最佳方法。

问题和反馈

报告 Issue

如果您在使用远程开发扩展程序时遇到问题，请务必收集正确的日志，以便我们能够帮助诊断您的问题。

每个远程扩展程序都有一个用于查看其日志的命令。

您可以使用命令面板 (F1) 中的 Remote-SSH: Show Log(Remote-SSH: 显示日志) 获取 Remote - SSH 扩展程序日志。在报告 Remote - SSH 问题时，另请验证您是否可以从外部终端（不使用 Remote - SSH）SSH 进入您的计算机。

同样，您可以使用 Dev Containers: Show Container Log(Dev Containers: 显示容器日志) 获取 Dev Containers 扩展程序日志。

与上述两个类似，您可以使用 WSL: Show Log(WSL: 显示日志) 获取 WSL 扩展程序日志。另请检查您的问题是否正在 WSL 仓库 中进行上游跟踪（并且不是由于 WSL 扩展程序引起的）。

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

注意：如果您只看到 日志(扩展主机)，则这是本地扩展主机，并且远程扩展主机未启动。这是因为日志通道仅在创建日志文件后才创建，因此如果远程扩展主机未启动，则远程扩展主机日志文件未创建且未在“输出”视图中显示。这仍然是有助于在您的 Issue 中包含的信息。

远程问题和反馈资源

我们有各种其他远程资源

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