远程开发提示和技巧

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

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

SSH 小贴士

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

定制 AI 聊天回复

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

您可以使用自定义指令来向 Copilot 提供有关您连接的远程环境类型更多信息（例如安装了哪些语言或工具链）。您可以使用一个Copilot指示.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：

如果 ($env:VSCODE_INJECTION -等于 "1") {
    $env:EDITOR = "code --等待"  # 或 'code-insiders' 用于 VS Code Insiders
}

现在正在运行一个终端命令，使用了 $EDITOR 变量，像提交更改将会在 VS Code 中打开文件，而不是默认的基于终端的编辑器（如维姆或纳米)。

配置基于密钥的认证

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

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

快速开始：使用 SSH 密钥

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

创建您的本地 SSH 密钥对

检查你是否已经在你的本地机器上有一个SSH密钥。这通常位于~/.ssh/id_ed25519.pub在 macOS / Linux，并且.ssh在Windows中，您的用户配置文件文件夹中的目录（例如C:\Users\your-user\.ssh\id_ed25519.pub)。

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

ssh-keygen -t ed25519 -b 4096

提示： 没有 ssh-keygen? 安装 一个支持的 SSH 客户端.

限制私钥文件的权限

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

  chmod 400 ~/.ssh/id_ed25519
  

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

  icacls "privateKeyPath" /grant <用户名>:R
  

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

授权您的 macOS 或 Linux 机器连接

在本地终端Windows中执行以下命令之一，替换用户名和主机名以将你的本地公钥复制到SSH主机。

• 连接到一个macOS 或 Linux SSH主机：

  导出 用户@主机="你在主机上的用户名@主机名"
  导出 公钥路径="$HOME/.ssh/id_ed25519.pub"
  
  ssh-copy-id -i "$PUBKEYPATH" "$USER_AT_HOST"
  

• 连接到一个Windows SSH主机：

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

    导出 用户@主机="你在主机上的用户名@主机名"
    导出 公钥路径="$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")'"
    

  • 否则：

    导出 用户@主机="你在主机上的用户名@主机名"
    导出 公钥路径="$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 主机上的 文件夹由您拥有，其他用户没有权限访问它。请参阅 OpenSSH 维基 了解详细信息。

授权您的Windows机器连接

在本地PowerShellWindows中运行以下命令之一，替换用户和主机名以将您的本地公钥复制到SSH主机。

• 连接到一个macOS 或 Linux SSH主机：

  $USER_AT_HOST="你的主机用户名@主机名"
  $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="你的主机用户名@主机名"
    $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="你的主机用户名@主机名"
    $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 主机上的 文件夹由您拥有，其他用户没有权限访问它。请参阅 OpenSSH 维基 了解详细信息。

通过专用密钥提高您的安全性

虽然在所有 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主机上的密钥，但设置公钥路径到id_ed25519-remote-ssh.pub请将以下文本翻译成中文: file instead.

3. 在 VS Code 中，运行 Remote-SSH: Open Configuration File... 在命令面板 (F1)，选择一个 SSH 配置文件，并添加 (或修改) 一个主机条目如下：

   这里ssh主机的主机名
       用户在主机上的用户名
       主机名 host-fqdn-or-ip-goes-here
       识别文件 ~/.ssh/id_ed25519-remote-ssh
   

   提示： 你可以使用 输入：/对于Windows路径也是如此。如果你使用输入：你需要使用两个反斜杠。例如，C:\\路径\\到我的\\id_ed25519输入：.

在 PuTTYGen 中生成的密钥重复使用

如果你使用PuTTYGen为你要连接的主机设置SSH公钥认证，你需要将你的私钥转换成其他SSH客户端可以使用的形式。为此：

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

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

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

4. 在 VS Code 中，运行 Remote-SSH: Open Configuration File... 在命令面板中 (F1)，选择您要更改的 SSH 配置文件，并在配置文件中添加 (或修改) 一个 host 条目，如下所示，以指向该文件：

   这里ssh主机的主机名
       用户名在主机上
       主机名 host-fqdn-or-ip-goes-here
       证书文件 ~/.ssh/exported-keyfile-from-putty
   

改进多用户服务器的安全性

The Remote - SSH 扩展安装和维护“VS Code Server”。服务器使用随机生成的密钥启动，任何新的连接到服务器都需要提供密钥。密钥存储在远程的磁盘上，仅当前用户可读。有一个HTTP路径在没有身份验证的情况下可用/版本输入：.

默认情况下，服务器监听本地主机 到一个随机的TCP端口，然后转发到你的本地机器。如果你连接到一个 Linux 或 macOS 主机，你可以切换到使用锁定到特定用户的Unix套接字。然后这个套接字会被转发而不是端口。

注意： 此设置禁用了连接复用，因此建议配置公钥认证。

要配置它：

1. 确保你在Windows、macOS或Linux上有一个本地OpenSSH 6.7+ SSH客户端，并且有一个OpenSSH 6.7+ Linux或macOS主机（Windows不支持此模式）。

2. Switch Remote - 通过启用Remote.SSH: 远程服务器在套接字上监听在你的本地 VS Code 用户设置中进入 socket 模式进行 SSH 连接。

   

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

如果您在连接时遇到错误，您可能需要在您的 SSH Host 的sshd 配置中启用 socket 转发。为此：

1. 打开/etc/ssh/sshd_config在文本编辑器（如 vi、nano 或 pico）中，在 SSH 主机上进行，而不是本地进行。
2. 添加设置 允许流本地转发 yes输入：.
3. 重启SSH服务器。（在Ubuntu上，运行请将以下网页文本翻译成中文，只输出翻译结果，不输出任何其他解释，若文本已经是中文了，则直接用中文复述一遍。翻译结果保持格式不变。输入：sudo systemctl restart sshd。(。)
4. 重试。

故障排除悬挂或失败的连接

如果你在尝试连接时遇到 VS Code 挂起（并可能超时）的问题，可以尝试以下几种方法来解决该问题。

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

一个对多种远程SSH问题很有帮助的命令是远程SSH：在主机上杀死VS Code服务器。这将移除服务器，可以解决您可能看到的广泛问题和错误信息，例如“无法建立到服务器名称VS Code 服务器启动失败。

看看 VS Code 是否在等待提示

启用远程.SSH.显示登录终端 设置 在 VS Code 中并重试。如果您被要求输入密码或令牌，请参阅启用替代的 SSH 认证方法 以了解减少提示频率的详细信息。

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

"远程.SSH.显示登录终端"：真，
"远程.SSH.使用本地服务器"：假

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

由于某些版本的 OpenSSH Windows 服务器存在一个错误，默认检查以确定主机是否运行 Windows 可能无法正常工作。此问题不会出现在随 Windows 1909 及更低版本发布的 OpenSSH 服务器中。

幸运的是，你可以通过明确告诉 VS Code 你的 SSH 主机是否运行 Windows 来绕过这个问题，方法是添加以下内容到settings.json输入：

"remote.SSH.useLocalServer"： false

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

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

修复已经合并，所以这个问题应该在服务器版本 8.1.0.0 及以后的版本中得到解决。

在远程主机上启用TCP转发

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

打开失败：行政上禁止：打开失败

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

1. 打开/etc/ssh/sshd_config或C:\ProgramData\ssh\sshd_config在文本编辑器（如Vim、nano、Pico或Notepad）中进行，而不是在本地进行。
2. 添加设置 允许TCP转发 是输入：.
3. 重启SSH服务器。（在Ubuntu上，运行请将以下网页文本翻译成中文，只输出翻译结果，不输出任何其他解释，若文本已经是中文了，则直接用中文复述一遍。翻译结果保持格式不变。输入：sudo systemctl restart sshd在 Windows 上，以管理员身份运行 PowerShell，重启服务 sshd)。
4. 重试。

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

如果您在代理服务器后面并且无法连接到您的SSH主机，您可能需要使用代理命令 您主机的参数在 本地 SSH配置文件中。您可以阅读 SSH ProxyCommand文章以了解其用法示例。

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

远程机器必须能够访问互联网，才能从市场下载VS Code Server和扩展。请参阅详细信息了解连接要求。

在远程主机上设置HTTP_PROXY / HTTPS_PROXY

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

导出 HTTP_PROXY=http://Agent.完全限定域名.或.IP:3128
导出 HTTPS_PROXY=$HTTP_PROXY

# 或者如果使用认证代理
导出 HTTP_PROXY=http://用户名:密码@Agent.完全限定域名.或者.IP:3128
导出 HTTPS_PROXY=$HTTP_PROXY

工作周围/tmp安装有禁止执行

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

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

一些用户从他们的启动一个不同的外壳.bash_profile 或者他们在 SSH主机 上的其他启动脚本，因为他们想使用不同于默认的 shell。这可能会破坏 VS Code 的远程服务器安装脚本，不推荐这样做。相反，使用 输入：chsh更改远程机器上的默认 shell。

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

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

解决此问题的一种方法是使用控制主机 OpenSSH 的选项（仅限 macOS/Linux 客户端），描述在 启用备用 SSH 认证方法，这样 VS Code 的两个连接将通过到同一节点的单个 SSH 连接进行多路复用。

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

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

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

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

启用替代的 SSH 认证方法

如果您正在连接到一个SSH远程主机，并且您是：

• 使用双重身份验证进行连接
• 使用密码认证
• 当SSH Agent未运行或无法访问时，使用带有密码的 SSH 密钥

然后 VS Code 应该会自动提示您输入所需信息。如果您没有看到提示，请启用远程.SSH.显示登录终端 在 VS Code 中设置。此设置会在 VS Code 运行 SSH 命令时显示终端。终端出现后，您可以输入您的认证代码、密码或口令。

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

"远程.SSH.显示登录终端"：真，
"远程.SSH.使用本地服务器"：假

如果您正在使用 macOS 和 Linux，并且希望减少输入密码或令牌的频率，您可以启用控制主机 在你的 本地机器 上启用该功能，以便 OpenSSH 能够在一个连接上运行多个 SSH 会话。

启用控制主机输入：

1. 在你的 SSH 配置文件中添加如下条目：

   主机 *
       ControlMaster 自动
       ControlPath  ~/.ssh/sockets/%r@%h-%p
       ControlPersist  600
   

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

设置 SSH 代理

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

为了验证代理是否正在运行并且可以从 VS Code 的环境访问，请运行ssh-add -l在本地 VS Code Windows的终端中。你应该会看到代理中密钥的列表（或者没有密钥的消息）。如果代理没有运行，请按照这些说明启动它。启动代理后，请确保重启 VS Code。

Windows:

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

# 确保你以管理员身份运行
Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent
Get-Service ssh-agent

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

Linux:

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

评估 "$(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 Agent 在远程设备上可用

在你的本地机器上有一个 SSH 代理允许 Remote - SSH 扩展在不反复提示输入密码的情况下连接到你选择的远程系统，但是像 Git 这样的在远程运行的工具无法访问你本地解锁的私钥。

你可以通过在远程上打开集成终端并运行来查看这一点ssh-add -l命令应该列出解锁的密钥，但相反却报告无法连接到认证代理的错误。设置转发代理 是使本地 SSH 代理在远程环境中可用，解决了这个问题。

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

主机 *
    前置代理 是

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

修复 SSH 文件权限错误

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

本地 SSH 文件和文件夹权限

macOS / Linux:

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

Windows:

具体的预期权限可能会因您使用的具体 SSH 实现而有所不同。我们建议使用盒子里的Windows 10 OpenSSH 客户端。

在这种情况下，请确保所有文件在.ssh 您在 SSH 主机上的远程用户文件夹由您拥有，其他用户没有访问权限。请参阅 Windows OpenSSH 维基 了解详细信息。

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

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

macOS / Linux:

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

请注意，目前仅支持 Linux 主机，这就是为什么没有包括 macOS 和 Windows 10 的权限。

Windows:

请参阅Windows OpenSSH 维基以了解为 Windows OpenSSH 服务器设置正确文件权限的详细信息。

安装支持的 SSH 客户端

VS Code将查找安全外壳协议在 PATH 中的命令。如果找不到，Windows 系统将尝试找到ssh.exe在默认的Git for Windows安装路径中。你也可以通过添加特定路径来告诉VS Code在哪里找到SSH客户端。远程.SSH.路径属性到settings.json输入：.

安装支持的 SSH 服务器

解决在 SSH 主机上进行 Git 推送或同步时卡住的问题

如果你通过 SSH 克隆一个 Git 仓库，并且你的 SSH 密钥有密码，VS Code 的拉取和同步功能在远程运行时可能会卡住。

使用没有密码的SSH密钥，或者使用HTTPS克隆，或者运行git 推送从命令行解决此问题。

使用 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 图形用户界面。

要使用命令行，请在本地终端中运行以下命令（替换用户@主机名与远程用户和主机名/ 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完成后，您可以使用操作系统中的文件资源管理器/文件管理器卸载它，或使用命令行：

卸载 "$HOME/sshfs/$USER_AT_HOST"

Windows:

请按照以下步骤操作：

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

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

3. 一旦你为Windows安装了SSHFS，你就可以使用文件资源管理器的映射网络驱动器... 选项，路径为\sshfs\用户名@主机名，其中用户@主机名是您的远程用户和主机名/ IP。您可以使用命令提示符按如下方式脚本化此操作：net use /PERSISTENT:NO X: \\sshfs\user@hostname

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

从终端连接到远程主机

一旦主机被配置好，你就可以通过传递远程URI直接从终端连接到它。

例如，连接到远程服务器并打开/code/我的项目文件夹，运行：

代码 --远程 ssh-远程+远程服务器 /代码/我的项目

我们需要对输入路径是文件还是文件夹进行一些猜测。如果它有文件扩展名，则认为是文件。

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

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

为了强制打开文件，请添加--跳转或者使用：

代码 -- 文件路径 vscode-remote://ssh-remote+remote_server/code/fileWithoutExtension

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

替代使用SSHFS访问远程文件的方法是使用rsync将远程主机上的整个文件夹内容复制到您的本地机器。rsync命令每次运行时都会确定需要更新的文件，这比使用像这样的命令要高效和方便得多。SCP或安全文件传输协议这主要是考虑如果你真的需要使用多文件或性能密集型的本地工具。

该rsync命令在 macOS 中开箱即用，也可以使用 Linux 包管理器安装（例如请将以下文本翻译成中文: sudo apt-get install rsync在 Debian/Ubuntu 上）。对于 Windows，您需要使用 WSL 或 Cygwin 来访问命令。

要使用该命令，请导航到您希望存储同步内容的文件夹并运行以下命令，将 用户@主机名与远程用户和主机名/ IP以及/远程/源代码/路径与远程源代码位置。

在 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 Server

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

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

# 终止服务器进程
kill -9 $(ps aux | grep vscode-server | grep $USER | grep -v grep | awk '{print $2}')
# 删除相关文件和文件夹
rm -rf $HOME/.vscode-server # 或 ~/.vscode-server-insiders

VS Code Server 之前安装在~/.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 命令行来添加wget和ca-certificates输入：

超级用户权限 软件包管理工具 更新 并且 超级用户权限 软件包管理工具 安装 下载工具 证书管理工具

阿尔卑斯

以 root 用户身份打开 Alpine WSL 壳 (WSL -d Alpine -u root) 添加libstdc++输入：

apk 更新 && apk 添加 libstdc++

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

apk 更新 && apk 添加 bash

选择WSL扩展使用的发行版

WSL: 新Windows将打开默认注册的WSL发行版。

要打开非默认的发行版，请运行代码 从发行版的WSL外壳使用或使用 WSL：使用发行版的新Windows.

对于 Windows 10 之前的 WSL 版本，May 2019 更新（版本 1903）之前，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终端无法工作，因为代码无法找到，您可能在WSL中缺少一些PATH的关键位置。

检查方法是打开WSL终端并输入回显 $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=“您的 Windows 别名”

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

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

使用 'code' 命令查找问题

如果输入代码从Windows命令提示符启动VS Code没有反应，您可以通过运行来帮助我们诊断问题VSCODE_WSL_DEBUG_INFO=true code .输入：.

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

正在查找与服务器启动或连接有关的问题

当WSLWindows无法连接到远程服务器时，您可以在WSL日志中获取更多信息。在提交问题时，非常重要的一点是要始终发送WSL日志的全部内容。

通过运行命令打开WSL日志WSL: 打开日志。日志将在WSL标签下的终端视图中显示。

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

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

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

在Windows命令提示符中：

• 执行代码 --定位扩展 ms-vscode-remote.remote-wsl确定WSL扩展文件夹。
• 光盘到返回的路径。
• 打开wsłServer.sh使用 VS Code 编写脚本代码 .\scripts\wslServer.sh输入：.
• 在最后一行之前 (之前"$(VSCODE_REMOTE_BIN.COMMIT.bin.SERVER_APPNAME)" "$(*)"), 添加 ulimit -C 无限制输入：.
• 启动WSLWindows运行远程服务器并等待段错误。

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

我看到 EACCES: 权限被拒绝错误，尝试在打开的工作区中重命名一个文件夹。

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

为了避免该问题，请设置远程.WSL.文件监视器.轮询然而，基于轮询的方法对大型工作区有性能影响。

对于大型工作区，您可能需要增加轮询间隔。远程.WSL.文件监视器.轮询间隔, 并控制被监视的文件夹

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

在WSL中解决Git行尾问题（导致许多修改后的文件）

由于Windows和Linux使用不同的默认行结束符，Git可能会报告大量没有实际差异的修改文件，只是因为它们的行结束符不同。为了避免这种情况发生，您可以禁用行结束符转换。.gitattributes文件或全局在Windows侧。

通常添加或修改一个 .gitattributes将文件放在你的代码库中是解决这个问题的最可靠方法。将此文件提交到源代码控制将有助于他人，并允许你根据需要在不同的代码库中更改行为。例如，添加以下内容到.gitattributes将文件放置在你的仓库根目录将强制所有内容使用 LF，除了需要 CRLF 的 Windows 批处理文件：

* 文本=自动 eol=换行
*.{命令,[cC][mM][dD]} 文本 eol=回车换行
*.{批处理,[bB][aA][tT]} 文本 eol=回车换行

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

如果您仍然希望始终上传 Unix 样式的行结束符 (LF)，您可以使用输入选项。

git 配置 --全局 core.autocrlf 输入

如果你希望完全禁用行尾转换，请运行以下命令：

git 配置 --全局 core.autocrlf 假

最后，您可能需要再次克隆该仓库以使这些设置生效。

在 Windows 和 WSL 之间共享 Git 凭证

如果你使用 HTTPS 克隆你的仓库，并且在 Windows 上配置了凭证助手，你可以与 WSL 共享，这样你输入的密码会在双方持久化。（注意，这不适用于使用 SSH 密钥。）

只需按照以下步骤操作：

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

   git config --global credential.helper wincred
   

2. 在WSL中配置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 仓库，并且你的 SSH 密钥有密码，VS Code 的拉取和同步功能在远程运行时可能会卡住。

使用没有密码的SSH密钥，或者使用HTTPS克隆，或者运行git 推送从命令行解决此问题。

GitHub 代码空间小贴士

关于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）中执行。你可能还需要添加"extensions.autoUpdate": false至settings.json 防止自动更新到最新的Marketplace版本。请参阅 支持远程开发 以获取在远程环境中开发和测试扩展的更多信息。

浏览器无法在本地打开

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

分辨率： 该扩展可以使用 vscode.env.openExternal API 用于解决此问题。请参阅 扩展作者指南 了解详细信息。

剪贴板无法工作

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

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

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

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

分辨率： 扩展可以使用 vscode.env.openExternal或vscode.env.asExternalUriAPIs（自动转发本地主机端口）来解决此问题。请参阅扩展作者指南了解详细信息。作为临时解决方案，请使用转发端口命令手动进行。

网页内容未显示

如果扩展的网页视图内容使用了一个内嵌框架要连接到本地网页服务器，网页视图连接到的端口可能会被阻止。此外，如果扩展程序硬编码vscode 资源://使用URI而不是使用asWebviewUri内容可能不会在Codespaces浏览器编辑器中显示。

分辨率： 该扩展可以使用 webview.asWebviewUri解决以下问题vscode 资源://统一资源标识符 (URIs)。

如果端口被阻止，最好的方法是改用webview消息传递 API。作为一种解决方法，vscode.env.asExternalUri 可以用于允许WebView从VS Code连接到启动的本地主机Web服务器。然而，这目前被 MicrosoftDocs/vscodespaces#11 阻止。请参阅 扩展作者指南 了解详细的解决方法。

阻止了本地主机端口

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

分辨率： VS Code 1.40 引入了一个新的vscode.env.asExternalUri 用于扩展的API，可以编程转发任意端口。 详情请参阅 扩展作者指南。 作为一种解决方案，您可以使用 手动转发端口 命令来实现。

存储扩展数据时出错

扩展可能会通过寻找来尝试持久化全局数据~/.config/Code在 Linux 上的文件夹。这个文件夹可能不存在，这可能会导致扩展抛出错误，例如ENOENT: 没有这样的文件或目录，打开 '/root/.config/Code/User/filename-goes-here输入：.

分辨率： 扩展可以使用 上下文.全局存储uri或上下文.存储Uri 属性来解决这个问题。请参阅 扩展作者指南 了解详细信息。

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

需要登录的扩展可能会使用其自己的代码来持久化密钥。这个代码可能会因为缺少依赖项而失败。即使成功，密钥也会远程存储，这意味着您必须为每个新端点登录。

分辨率： 扩展可以使用 SecretStorage API 来解决这个问题。详情请参阅 扩展作者指南。

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

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

分辨率： 按照以下步骤手动删除远程扩展文件夹：

1. 对于容器，请确保你的devcontainer.json不再包含对有故障扩展的引用。

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

   • 如果使用 SSH 或 WSL，则相应地连接到环境（运行安全外壳协议连接到服务器或打开WSL终端）。
   • 如果使用容器，请通过调用来标识容器IDdocker ps -a查找具有正确名称的图像。如果容器已停止，请运行docker run -it 如果它在运行，请运行docker exec -it 输入：.

3. 一旦连接，请运行rm -rf ~/.vscode-server/extensions对于 VS Code 稳定版和/或rm -rf ~/.vscode-server-insiders/extensions供 VS Code 内部人员移除所有扩展。

发布或获取预构建原生模块的扩展失败

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

分辨率： 需要修改扩展来解决此问题。它们需要包含（或动态获取）Node.js中VS Code所搭载的“modules”版本的两套二进制文件（Electron和标准Node.js），然后检查上下文.执行上下文 === vscode.扩展执行上下文.远程 在其激活函数中设置正确的二进制文件。请参阅 扩展作者指南 了解详细信息。

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

如果一个扩展在 Debian 9+、Ubuntu 16.04+ 或 RHEL / CentOS 7+ 的远程 SSH 主机、容器或 WSL 上可以正常工作，但在支持的非 x86_64 主机（例如 ARMv7l）或 Alpine Linux 容器上失败，那么该扩展可能只包含原生代码或不支持这些平台的运行时。例如，该扩展可能只包含 x86_64 编译版本的原生模块或运行时。对于 Alpine Linux，所包含的原生代码或运行时可能由于 基本差异 而无法工作。libc在Alpine Linux中实施穆斯林) 和其他分布 (glibc)。

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

扩展因缺少模块而失败

依赖于 Electron 或 VS Code 基础模块（未暴露在扩展 API 中）且没有提供回退的扩展在远程运行时可能会失败。您可能会在开发者工具控制台中看到类似于以下的错误：原始文件系统未找到。

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

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

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

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

无法从扩展访问附加设备

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

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

问题和反馈

报告问题

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

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

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

同样，您可以使用Dev Containers: 显示容器日志来获取 Dev Containers 扩展日志。

与上面两个相同，您可以通过WSL: 显示日志获取WSL扩展的日志。同时，请检查您的问题是否在WSL仓库中被跟踪（并且不是由于WSL扩展引起的）。

如果你在远程使用其他扩展时遇到问题（例如，其他扩展在远程上下文中无法正常加载或安装），从远程扩展主机输出通道（输出：聚焦输出视图）获取日志，并选择日志（远程扩展主机）从下拉菜单中。

注意：如果您只看到Log (扩展主机)，这是本地扩展主机，而远程扩展主机没有启动。这是因为日志通道只有在日志文件创建后才会创建，所以如果远程扩展主机没有启动，远程扩展主机日志文件将不会创建，并且不会在输出视图中显示。这仍然是包含在您的问题中的有用信息。

远程问题和反馈资源

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

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