远程开发技巧和窍门

本文涵盖了 Visual Studio Code 远程开发 扩展的故障排除技巧和窍门。有关设置和使用每个特定扩展的详细信息，请参阅 SSH、容器 和 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) 中运行 远程-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. 从应用程序菜单中选择 转换 > 导出 OpenSSH 密钥。将转换后的密钥保存到用户配置文件文件夹中的 `.ssh` 目录下的 本地 位置（例如 `C:\Users\youruser\.ssh`）。

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

4. 在 VS Code 中，在命令面板 (F1) 中运行 远程-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
   

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

远程 - 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 Server Listen On Socket，将 Remote - SSH 切换到套接字模式。

   

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

如果您在连接时遇到错误，您可能需要在 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: 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 服务器版本中的错误

由于某些版本的 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 文章 以获取其用法的示例。

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

远程机器必须能够访问互联网才能从 Marketplace 下载 VS Code Server 和扩展。有关连接要求的详细信息，请参阅 常见问题解答。

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

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

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

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

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

联系您的系统管理员寻求配置帮助

SSH 是一个非常灵活的协议，支持多种配置。如果您在登录终端或 Remote-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` 来创建套接字文件夹。

设置 SSH 代理

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

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

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

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

代理在 macOS 上应默认运行。

使本地 SSH 代理在远程上可用

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

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

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

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

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

安装受支持的 SSH 服务器

解决在 SSH 主机上进行 Git push 或 sync 时挂起的问题

如果您使用 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 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 服务器以前安装在 `~/.vscode-remote` 下，因此您也可以检查该位置。

SSH 到远程 WSL 2 主机

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

提交问题

如果您在使用 Remote-SSH 扩展时遇到问题，并认为您需要提交问题，请首先确保您已阅读本网站上的文档，然后参阅 故障排除 wiki 文档，了解如何获取日志文件并尝试更多有助于缩小问题来源的步骤。

开发容器提示

如果您想了解有关使用开发容器的提示，可以访问开发容器 提示和技巧。

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 月更新 (build 1803) 及更早版本中，需要 `/bin/bash`

apk update && apk add bash

选择 WSL 扩展使用的发行版

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

要打开非默认发行版，请从要使用的发行版的 WSL shell 中运行 `code .` 或使用 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 initialization。大多数 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 中运行以下命令来配置 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 ` 以安装所需的库。检查您的扩展或错误消息中提到的运行时的文档以获取其他安装详细信息。

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

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

解决方案： 连接到远程端点后，您可以从命令面板 (F1) 运行 Preferences: Open Remote Settings 命令或在“设置”编辑器中选择 远程 选项卡来设置特定于端点的设置。这些设置将在您连接时覆盖您已有的任何本地设置。

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

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

解决方案： 连接到 SSH 主机、容器或 WSL 后，您可以像在本地一样安装 VSIX。从命令面板 (F1) 运行 Extensions: Install from 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 服务器。但是，由于 MicrosoftDocs/vscodespaces#11，这目前被 Codespaces 基于浏览器的编辑器（仅限）阻止。有关解决方法的详细信息，请参阅 扩展作者指南。

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 /bin/sh`。如果它正在运行，请运行 `docker exec -it /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 中的“模块”版本，然后在其激活函数中检查 `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 扩展引起的问题）。

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

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

远程问答和反馈资源

我们有各种其他远程资源

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