远程开发技巧

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

有关 GitHub Codespaces 的技巧和问题，请参阅 GitHub Codespaces 文档。

SSH 技巧

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

自定义 AI 聊天响应

自定义指令可让您描述通用准则或规则，以获得符合您特定编码实践和技术栈的响应。

您可以使用自定义指令为 Copilot 提供有关您连接到的远程环境类型（例如安装了哪些语言或工具链）的更多信息。您可以像在本地一样使用 copilot-instructions.md 文件。在使用开发容器时，您还可以执行 其他指令配置步骤。

配置 $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: 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. 从应用程序菜单中选择Conversions > Export OpenSSH key。将转换后的密钥保存到用户配置文件文件夹中 .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 客户端，并在 Linux 或 macOS 主机上拥有OpenSSH 6.7+（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. 在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 Server 启动失败。”

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

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

如果仍有问题，请在 settings.json 中设置以下属性并重试

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

解决 Windows OpenSSH 服务器某些版本中的 bug

由于 Windows 上的某些 OpenSSH 服务器版本存在 bug，用于确定主机是否正在运行 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 config

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

确保远程机器具有 Internet 访问权限

远程机器必须具有 Internet 访问权限才能从 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

解决 /tmp 挂载了 noexec 的问题

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

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

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

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

一些系统会在每次建立 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: Open Configuration File...。然后，您可以与管理员一起添加必要的设置。

启用备用 SSH 身份验证方法

如果您正在连接到 SSH 远程主机并且

• 使用双因素身份验证进行连接
• 使用密码身份验证
• 在使用带密码短语的 SSH 密钥，但 SSH Agent 未运行或不可访问

那么 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 来创建套接字文件夹。

设置 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 来看到这一点。该命令应该会列出已解锁的密钥，但会报告无法连接到身份验证代理的错误。设置 ForwardAgent yes 可使本地 SSH Agent 在远程环境中可用，从而解决此问题。

您可以通过编辑 .ssh/config 文件（或 Remote.SSH.configFile 设置为的任何内容 - 使用Remote-SSH: Open SSH Configuration File...命令确保）并添加以下内容来执行此操作

Host *
    ForwardAgent yes

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

修复 SSH 文件权限错误

SSH 对文件权限要求严格，如果设置不正确，您可能会看到类似“警告：未受保护的私钥文件！”的错误。有几种方法可以更新文件权限来修复此问题，具体将在下面的部分中介绍。

本地 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 客户端

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 差异而导致的意外问题。有关详细信息，请参阅 解决 WSL 中的 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 等工具效率更高、更方便。这主要是一个需要考虑的选项，如果您确实需要使用多文件或性能要求高的本地工具。

macOS 和 Linux 上默认提供 rsync 命令，并且可以使用 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 上的 WSL PowerShell

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 Server

SSH 扩展提供了一个用于从远程机器清理 VS Code Server 的命令，Remote-SSH: Uninstall VS Code Server from Host...。该命令执行两项操作：它会终止所有正在运行的 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。

提交问题

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

Dev Containers 技巧

如果您想阅读有关使用 Dev Containers 的技巧，可以转到 Dev Containers 技巧。

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 April 2018 Update（build 1803）及更早版本中，需要 /bin/bash

apk update && apk add bash

选择 WSL 扩展使用的发行版

WSL: New Window 将打开注册为默认值的 WSL 发行版。

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

对于早于 Windows 10 May 2019 Update（版本 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 命令无法工作的问题

如果在 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 选项卡下显示。

要获得更详细的日志记录，请在用户设置中启用 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: permission denied 错误

这是 WSL 文件系统实现的一个已知问题（Microsoft/WSL#3395，Microsoft/WSL#1956），由 VS Code 激活的文件监视器引起。该问题将在 WSL 2 中修复。

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

对于大型工作区，你可能希望增加轮询间隔 remote.WSL.fileWatcher.pollingInterval，并通过 控制要监视的文件夹。

WSL 2 没有此文件监视器问题，并且不受新设置的影响。

解决 WSL 中 Git 行尾问题（导致大量文件修改）

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

通常，在存储库中添加或修改 .gitattributes 文件是解决此问题的最可靠方法。将此文件提交到源代码管理将有助于他人，并允许你根据需要为每个存储库调整行为。例如，将以下内容添加到存储库根目录的 .gitattributes 文件中，会将所有文件强制转换为 LF，但 Windows 批处理文件除外，后者需要 CRLF。

* 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 push 或 sync 时挂起的问题

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

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

GitHub Codespaces 技巧

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

扩展技巧

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

解决缺少依赖项的错误

某些扩展依赖于某些 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...** 命令。你还可以考虑在 settings.json 中添加 "extensions.autoUpdate": false 来防止自动更新到最新的 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. 连接后，运行 rm -rf ~/.vscode-server/extensions（适用于 VS Code 稳定版）和/或 rm -rf ~/.vscode-server-insiders/extensions（适用于 VS Code Insiders 版）以删除所有扩展。

包含或获取预编译本地模块的扩展失败

与 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 与远程工作区文件系统进行交互。然后，你可以将其作为“工作区”扩展的依赖项，并在需要时通过命令调用它。有关不同类型的扩展以及如何使用命令在它们之间进行通信的详细信息，请参阅 扩展作者指南。

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

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

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

问题和反馈

报告问题

如果你在远程开发扩展中遇到问题，收集正确的日志至关重要，以便我们能够帮助 诊断你的问题。

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

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

同样，你可以通过 **Dev Containers: Show Container Log** 命令获取 Dev Containers 扩展日志。

与上面两个类似，你可以通过 **WSL: Show Log** 命令获取 WSL 扩展日志。同时检查你的问题是否在 WSL 仓库 中被跟踪（而不是由于 WSL 扩展引起）。

如果你在使用其他扩展进行远程开发时遇到问题（例如，其他扩展在远程上下文中未正确加载或安装），则从 **Remote Extension Host** 输出通道（**Output: Focus on Output View**）获取日志，并从下拉列表中选择 **Log (Remote Extension Host)** 会很有帮助。

注意： 如果你只看到 **Log (Extension Host)**，这是本地扩展主机，远程扩展主机未启动。这是因为日志通道仅在创建日志文件后创建，因此如果远程扩展主机未启动，则不会创建远程扩展主机日志文件，也不会在输出视图中显示。在你的 issue 中包含此信息仍然很有帮助。

远程问题和反馈资源

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

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