远程开发故障排除技巧和窍门

这篇文章涵盖了 Visual Studio Code 远程开发扩展的故障排除技巧和窍门。请参阅 SSH、容器和 WSL 文章，了解关于设置和使用每个特定扩展的细节。或者试试介绍性的教程，以帮助你在远程环境中快速运行。

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

SSH 提示

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

配置基于密钥的认证

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

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

快速入门。使用 SSH 密钥

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

创建你的本地 SSH 密钥对

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

如果你没有钥匙，在本地终端 / PowerShell 中运行以下命令来生成一个 SSH 钥匙对。

ssh-keygen -t rsa -b 4096

提示。没有 ssh-keygen？安装一个支持的 SSH 客户端。

授权你的 MacOS 或 Linux 机器进行连接

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

• 连接到 macOS 或 Linux 的 SSH 主机。
  ``` export USER_AT_HOST=”your-user-name-on-host@hostname” export PUBKEYPATH=”$HOME/.ssh/id_rsa.pub”

ssh-copy-id -i “$PUBKEYPATH” “$USER_AT_HOST”

-  连接到一个 Windows SSH 主机。 <br />你可能想确认 SSH 主机上的远程用户的. ssh 文件夹中的 authorized_key 文件是由你拥有的，没有其他用户有权限访问它。详情见 OpenSSH wiki。

export USER_AT_HOST=”your-user-name-on-host@hostname” export PUBKEYPATH=”$HOME/.ssh/id_rsa.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”)’”

**授权你的 Windows 机器进行连接**
在本地 PowerShell 窗口中运行以下命令之一，根据情况替换用户和主机名，将你的本地公钥复制到 SSH 主机上。
-  连接到一个 macOS 或 Linux SSH 主机。

$USER_AT_HOST=”your-user-name-on-host@hostname” $PUBKEYPATH=”$HOME.ssh\id_rsa.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 主机。 <br />确认 SSH 主机上远程用户的. ssh 文件夹中的 authorized_key 文件为你所有，没有其他用户有权限访问它。详情见 OpenSSH wiki。

$USER_AT_HOST=”your-user-name-on-host@hostname” $PUBKEYPATH=”$HOME.ssh\id_rsa.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"“”

<a name="2d67fb3d"></a>
### 用专用的密钥提高你的安全性#
虽然在所有的 SSH 主机上使用单一的 SSH 密钥是很方便的，但是如果有人获得了你的私人密钥，他们也将获得你所有主机的访问权。你可以通过为你的开发主机创建一个单独的 SSH 密钥来防止这种情况。只需遵循这些步骤。
1.  在一个不同的文件中生成一个单独的 SSH 密钥。<br />macOS / Linux。在本地终端运行以下命令。 <br />Windows。在本地 PowerShell 中运行下面的命令。

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa-remote-ssh

```
ssh-keygen -t rsa -b 4096  -f  "$HOME\.ssh\id_rsa-remote-ssh"

1. 按照快速入门中的相同步骤在 SSH 主机上授权密钥，但将 PUBKEYPATH 设置为 id_rsa-remote-ssh.pub 文件，而不是。
2. 在 VS 代码中，运行 Remote-SSH: Open Configuration File… in the Command Palette (F1)，选择一个 SSH 配置文件，并添加（或修改）一个主机条目，如下所示。

   Host name-of-ssh-host-here
   User your-user-name-on-host
   HostName host-fqdn-or-ip-goes-here
   IdentityFile ~/.ssh/id_rsa-remote-ssh

   提示：你也可以对 Windows 路径使用 /。如果你使用 \，你将需要使用两个斜线。例如，C:\path\to\my\id_rsa。

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

如果你用 PuTTYGen 为你连接的主机设置了 SSH 公钥认证，你需要转换你的私钥，以便其他 SSH 客户端可以使用它。要做到这一点。

1. 在本地打开 PuTTYGen，加载你想转换的私钥。
2. 从应用程序菜单中选择转换 > 导出 OpenSSH 密钥。将转换后的密钥保存到你的用户配置文件文件夹下的. ssh 目录下的一个本地位置（例如 C:\Users\youruser.ssh）。
3. 确认这个新的本地文件为你所有，没有其他用户有权限访问它。
4. 在 VS 代码中，运行 Remote-SSH: Open Configuration File… 在命令调色板（F1）中，选择你想改变的 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

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

默认情况下，”VS 代码服务器” 是由远程 - 容器扩展安装和维护的，当它在一个随机的 TCP 端口连接到 localhost，然后转发到你的本地机器。这意味着只有该机器上的用户可以访问该端口。然而，如果主机同时被许多用户使用，你可能想进一步锁定访问，以减少一个用户发现端口号并试图访问另一个用户的 VS Code Server 实例的机会。

如果你连接到一个 Linux 或 macOS 主机，你可以切换到使用锁定在一个特定用户的 Unix 套接字。然后这个套接字被转发，而不是端口。

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

要配置它。

1. 确保你在 Windows、macOS 或 Linux 上有一个本地 OpenSSH 6.7+ SSH 客户端和一个 OpenSSH 6.7+ Linux 或 macOS 主机（Windows 不支持这种模式）。
2. 通过在本地 VS 代码用户设置中启用 Remote.SSH: Remote Server Listen On Socket，将远程 - 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 服务器未能启动。”

查看 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 转发

远程 - SSH 扩展利用 SSH 隧道来促进与主机的通信。在某些情况下，这可能在你的 SSH 服务器上被禁用。要看看这是否是问题所在，在输出窗口中打开远程 - 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 重新启动 sshd。在 Windows 上，在管理员 PowerShell 中运行 Restart-Service sshd）。)
4. 重试。

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

如果你在代理服务器后面，无法连接到你的 SSH 主机，你可能需要在本地 SSH 配置文件中为你的主机使用 ProxyCommand 参数。你可以阅读这篇 SSH ProxyCommand 文章，了解它的使用实例。

确保远程机器有互联网接入

远程机器必须有互联网接入，以便能够从市场上下载 VS Code Server 和扩展。关于连接要求的细节，请看 FAQ。

在远程主机上设置 HTTP_PROXY / HTTPS_PROXY

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

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。这可能会破坏 VS Code 的远程服务器安装脚本，因此不建议这样做。相反，使用 chsh 来改变你在远程机器上的默认 shell。

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

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

一个解决方法是在 OpenSSH 中使用 ControlMaster 选项（仅适用于 macOS/Linux 客户端），在启用备用 SSH 认证方法中描述，这样 VS Code 的两个连接将通过一个 SSH 连接复用到同一个节点。

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

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

请联系你的系统管理员，了解你的 SSH 主机和客户端所需的设置信息。连接到 SSH 主机的特定命令行参数可以被添加到 SSH 配置文件中。

要访问你的配置文件，运行 Remote-SSH: Open Configuration File… in the Command Palette（F1）。然后你可以和你的管理员一起工作，添加必要的设置。

启用备用的 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 来创建 sockets 文件夹。

设置 SSH 代理

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

为了验证代理正在运行并且可以从 VS Code 的环境中到达，在本地 VS Code 窗口的终端运行 ssh-add -l。你应该看到代理中的密钥列表（或者一个没有密钥的消息）。如果代理没有运行，请按照下面的说明来启动它。启动代理后，一定要重新启动 VS Code。

Windows。

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

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

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

Linux:

要在后台启动 SSH 代理，请运行。

eval  "$(ssh-agent -s)"

要在登录时自动启动 SSH 代理，请在你的~/.bash_profile 中添加这些行。

if [ -z "$SSH_AUTH_SOCK" ]; then
  # Check for a currently running instance of the agent
 RUNNING_AGENT="`ps -ax | grep 'ssh-agent -s' | grep -v grep | wc -l | tr -d '[:space:]'`"
  if [ "$RUNNING_AGENT" = "0" ]; then
  # Launch a new instance of the agent
 ssh-agent -s &> .ssh/ssh-agent
  fi
  eval  `cat .ssh/ssh-agent`
fi

macOS:

代理在 macOS 上应该是默认运行的。

修复 SSH 文件权限错误

SSH 对文件权限有严格的要求，如果它们被错误地设置，你可能会看到诸如 “警告：未经保护的私人密钥文件！” 这样的错误。为了解决这个问题，有几种更新文件权限的方法，在下面的章节中有所描述。

本地 SSH 文件和文件夹的权限

macOS / Linux。

在你的本地机器上，确保设置了以下权限。

Windows。

具体的预期权限可能会有所不同，这取决于你所使用的确切的 SSH 实现。我们强烈建议使用开箱即用的 Windows 10 OpenSSH 客户端。

在这种情况下，确保 SSH 主机上的远程用户的. ssh 文件夹中的所有文件都为你所有，其他用户没有权限访问。详情请参见 Windows OpenSSH wiki。

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

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

macOS / Linux。

在你所连接的远程机器上，确保设置了以下权限。

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

Windows。

请参阅 Windows OpenSSH wiki 以了解为 Windows OpenSSH 服务器设置适当文件权限的细节。

安装一个支持的 SSH 客户端

VS Code 会在 PATH 中寻找 ssh 命令。如果没有，在 Windows 上，它将尝试在默认的 Git for Windows 安装路径中找到 ssh.exe。你也可以通过在 settings.json 中添加 remote.SSH.path 属性来明确告诉 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 sshfs 此外，如果你不愿意使用命令行来装载远程文件系统，你也可以安装 SSHFS GUI。

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

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. 一旦你为 Windows 安装了 SSHFS，你可以使用文件资源管理器的 Map Network Drive… 选项，路径为：\sshfsuser@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 来访问该命令。

要使用该命令，导航到你想存储同步内容的文件夹，然后运行以下命令，用远程用户和主机名 / IP 替换 user@hostname，用远程源代码位置替换 / 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 代码服务器 #。

SSH 扩展提供了一个命令用于清理远程机器上的 VS Code Server，Remote-SSH: Uninstall VS Code Server from Host…. 该命令做了两件事：它杀死了任何正在运行的 VS Code Server 进程，并删除了安装该服务器的文件夹。

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

kill -9 `ps ax | grep "remoteExtensionHostAgent.js" | grep -v grep | awk '{print $1}'`
kill -9 `ps ax | grep "watcherService" | grep -v grep | awk '{print $1}'`
rm -rf ~/.vscode-server # Or ~/.vscode-server-insiders

VS 代码服务器以前是安装在~/.vscode-remote 下，所以你也可以检查这个位置。

SSH 进入远程 WSL 2 主机 #。

你可能想用 SSH 来连接到远程机器上运行的 WSL 发行版。请看这个指南，了解如何从外部机器上 SSH 进入 Windows 10 上的 Bash 和 WSL 2。

容器小贴士

本节包括一些提示和技巧，以便在不同的环境中启动和运行远程 - 容器扩展。

如果你遇到了 Docker 问题，或者不愿意在本地运行 Docker，你可能想试试 GitHub Codespaces 管理的基于云的环境预览。随着时间的推移，这项服务将支持越来越多的 devcontainer.json 属性，除了 VS Code 之外，你还可以使用其基于浏览器的编辑器。

用于 Windows 的 Docker 桌面提示

Docker Desktop for Windows 在大多数设置中运行良好，但也有一些 “小问题” 会导致问题。这里有一些避免这些问题的提示。

1. 考虑在 Windows 10（2004+）上使用新的 Docker WSL 2 后端。如果你使用 Docker Desktop 的 WSL 2 后端，你可以你在 WSL 内部以及本地打开文件夹。容器也可以在 Windows 和 WSL 内部共享，这个新引擎不容易受到文件共享问题的影响。详情见快速入门。
2. 切换出 “Windows 上的 Linux 容器（LCOW）” 模式。虽然默认情况下是禁用的，但最近版本的 Docker 支持 Windows 上的 Linux 容器（LCOW），可以让你同时使用 Windows 和 Linux 容器。然而，这是一个新功能，所以你可能会遇到问题，而且远程 - 容器扩展目前只支持 Linux 容器。你可以在任何时候切换出 LCOW 模式，方法是右击 Docker 任务栏项目，从上下文菜单中选择切换到 Linux 容器…。
3. 确保你的防火墙允许 Docker 建立一个共享驱动器。Docker 只需要在两台机器的本地 IP 之间进行连接，但一些防火墙软件可能仍然会阻止任何驱动器共享或所需的端口。关于解决这个问题的下一步，请看这篇 Docker KB 文章。

这里有一些适用于旧版 Docker for Windows 的提示，但现在应该已经解决了。如果你由于可能的回归而遇到奇怪的行为，这些提示在过去已经解决了问题。

1. 共享驱动器时，使用 AD 域账户或本地管理员账户。不要使用 AAD（基于电子邮件）账户。AAD（基于电子邮件的）账户有众所周知的问题，在 Docker 问题 #132 和问题 #1352 中有记载。如果你必须使用 AAD 账户，在你的机器上创建一个单独的本地管理员账户，纯粹用于共享驱动器。按照这篇博文中的步骤，把一切都设置好。
2. 坚持使用字母数字密码以避免驱动器共享问题。当被要求在 Windows 上共享驱动器时，你会被提示提供机器上具有管理权限的账户的用户名和密码。如果你被警告说用户名或密码不正确，这可能是由于密码中的特殊字符。例如，！、[ 和 ]是已知的会导致问题的字符。将你的密码改为字母数字字符来解决。详情请看这个关于 Docker 卷安装问题的问题。
3. 使用你的 Docker ID 登录到 Docker（而不是你的电子邮件）。Docker CLI 只支持使用你的 Docker ID，所以使用你的电子邮件会导致问题。请参阅 Docker 问题 #935 了解详情。

如果你仍然有问题，请参阅 Docker Desktop for Windows 故障排除指南。

在 Docker Desktop# 中启用文件共享

只有当你的代码在与 Docker 共享的文件夹或驱动器中时，VS Code Remote - Containers 扩展才能自动将你的源代码加载到容器中。如果你从一个非共享的位置打开一个开发容器，该容器将成功启动，但工作空间将是空的。

注意，Docker Desktop 的 WSL 2 引擎不需要这个步骤。

要改变 Docker 的驱动器和文件夹共享设置。

Windows。

1. 右键单击 Docker 任务栏项目，选择设置。
2. 进入 “资源”>”文件共享”，检查你的源代码所在的驱动器。
3. 如果你看到一条关于你的本地防火墙阻止共享行动的信息，请看这篇 Docker 知识库文章，了解下一步。

macOS。

1. 点击 Docker 菜单栏项目，选择首选项。
2. 转到资源 > 文件共享。确认包含你的源代码的文件夹是在所列的共享文件夹下。

解决容器中的 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），你可以使用输入选项。

git config --global core.autocrlf input

如果你想完全禁用行尾转换，可以运行下面的命令来代替。

git config --global core.autocrlf false

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

使用 Docker Compose 时避免在容器中设置 Git#。

有关解决这个问题的信息，请参见容器主文中的 “与容器共享 Git 凭据”。

解决从容器推送或同步 Git 时的挂起问题

如果你用 SSH 克隆了一个 Git 仓库，而你的 SSH 密钥有一个密码，VS Code 的拉取和同步功能在远程运行时可能会挂起。

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

解决关于缺失的 Linux 依赖的错误 #。

一些扩展依赖的库在某些 Docker 镜像中没有找到。请参阅容器文章，了解解决这个问题的几个选项。

加快 Docker Desktop 中的容器速度

默认情况下，Docker Desktop 只给容器提供机器容量的一小部分。在大多数情况下，这已经足够了，但如果你正在做一些需要更多容量的事情，你可以增加内存、CPU 或磁盘的使用。

首先，尝试停止任何你不再使用的正在运行的容器。

如果这还不能解决你的问题，你可能想看看 CPU 使用率是否真的是问题所在，或者是否有其他事情发生。检查这个问题的一个简单方法是安装资源监视器扩展。当安装在一个容器中时，它在状态栏中提供关于你的容器容量的信息。

如果你想让这个扩展总是被安装，请将此添加到你的 settings.json 中。

"remote.containers.defaultExtensions": [
  "mutantdino.resourcemonitor"
]

如果你确定你需要给你的容器提供更多的机器容量，请遵循以下步骤。

1. 右键点击 Docker 任务栏项目，选择设置 / 偏好。
2. 转到高级，增加 CPU、内存或交换空间。
3. 在 macOS 上，进入磁盘，增加 Docker 在你的机器上被允许消耗的磁盘量。在 Windows 上，这位于高级和其他设置下。

最后，如果你的容器正在进行磁盘密集型操作，或者你只是在寻找更快的响应时间，请参阅提高容器磁盘性能的提示。VS Code 的默认值为方便和普遍支持进行了优化，但也可以进行优化。

清理未使用的容器和镜像

如果你看到 Docker 报告你没有磁盘空间的错误，你通常可以通过清理未使用的容器和镜像来解决这个问题。有几种方法可以做到这一点。

方法 1：使用远程资源管理器

你可以通过选择远程资源管理器来删除容器，右键点击你想删除的容器，然后选择删除容器。

然而，这并不能清理你可能已经下载的任何镜像，这可能会使你的系统变得混乱。

选项 2：使用 Docker 扩展

1. 在 VS Code 中打开一个本地窗口（文件 > 新窗口）。
2. 从扩展视图中安装 Docker 扩展（如果尚未存在）。
3. 然后你可以进入 Docker 视图，展开容器或图像节点，右击，并选择删除容器 / 图像。
   

选项 3：使用 Docker CLI 来挑选要删除的容器

1. 打开一个本地终端 / 命令提示符（或在 VS Code 中使用本地窗口）。
2. 输入 docker ps -a 来查看所有容器的列表。
3. 输入 docker rm 从这个列表中删除一个容器。
4. 输入 docker image prune 来删除任何未使用的镜像。

如果 docker ps 没有提供足够的信息来识别你要删除的容器，下面的命令将列出 VS Code 管理的所有开发容器和用来生成它们的文件夹。

docker ps -a --filter="label=vsch.quality" --format "table {{.ID}}\t{{.Status}}\t{{.Image}}\tvscode-{{.Label \"vsch.quality\"}}\t{{.Label \"vsch.local.folder\"}}"

选项 4：使用 Docker Compose

1. 打开本地终端 / 命令提示符（或使用 VS Code 中的本地窗口）。
2. 转到有 docker-compose.yml 文件的目录。
3. 输入 docker-compose down 来停止和删除容器。如果你有一个以上的 Docker Compose 文件，你可以用 - f 参数指定额外的 Docker Compose 文件。

选项 4：删除所有未运行的容器和镜像。

1. 打开一个本地终端 / 命令提示符（或在 VS Code 中使用本地窗口）。
2. 输入 docker system prune —all。

解决使用 Debian 8# 的镜像的 Dockerfile 构建失败的问题

当构建使用基于 Debian 8/Jessie 的镜像的容器时 — 比如旧版本的 node:8 镜像 — 你可能会遇到以下错误。

...
W: Failed to fetch http://deb.debian.org/debian/dists/jessie-updates/InRelease  Unable to find expected entry 'main/binary-amd64/Packages' in Release file (Wrong sources.list entry or malformed file)
E: Some index files failed to download. They have been ignored, or old ones used instead.
...

这是一个众所周知的问题，由 Debian 8 被 “归档” 引起。较新版本的映像通常会解决这个问题，通常是通过升级到 Debian 9/Stretch。

有两种方法可以解决这个错误。

• 方法一：删除任何依赖映像的容器，删除映像，然后再尝试构建。这应该会下载一个不受问题影响的最新映像。详情见清理未使用的容器和镜像。
• 选项 2：如果你不想删除你的容器或镜像，在任何 apt 或 apt-get 命令之前，在你的 Docker 文件中添加这一行。它为 Jessie 添加了所需的源代码列表。

  # Add archived sources to source list if base image uses Debian 8 / Jessie
  RUN cat /etc/*-release | grep -q jessie && printf "deb http://archive.debian.org/debian/ jessie main\ndeb-src http://archive.debian.org/debian/ jessie main\ndeb http://security.debian.org jessie/updates main\ndeb-src http://security.debian.org jessie/updates main" > /etc/apt/sources.list

当使用电子邮件时，解决 Docker Hub 的登录错误 #。

Docker CLI 只支持使用你的 Docker ID，所以使用你的电子邮件来登录可能会导致问题。请参阅 Docker 问题 #935 了解详情。

作为一个变通方法，使用你的 Docker ID 来登录 Docker，而不是你的电子邮件。

macOS 上 Hyperkit 的 CPU 利用率很高 #。

Docker for Mac 有一个已知的问题，可以推动高 CPU 峰值。特别是，在观察文件和构建时，会出现高 CPU 使用率。如果你在活动监视器中看到 com.docker.hyperkit 的 CPU 使用率很高，而你的开发容器中几乎没有什么事情发生，你很可能遇到了这个问题。请关注 Docker 问题的更新和修复。

使用 SSH 隧道连接到一个远程 Docker 主机

在远程 Docker 机器或 SSH 主机上的容器内开发这篇文章涵盖了在与远程 Docker 主机一起工作时如何设置 VS Code。这通常是在 settings.json 中设置 Docker 扩展 docker.host 属性或 DOCKER_HOST 环境变量为 ssh:// 或 tcp:// 的 URI 那么简单。

然而，你可能会遇到这样的情况：由于 SSH 配置的复杂性或其他限制，这在你的环境中不起作用。在这种情况下，可以使用 SSH 隧道作为后备方案。

使用 SSH 隧道作为后备选项

你可以建立一个 SSH 隧道，将 Docker 套接字从远程主机转发到你的本地机器。

请按照以下步骤操作。

1. 安装一个 OpenSSH 兼容的 SSH 客户端。

2. 在你的用户或工作区设置. json 中更新 Docker 扩展 docker.host 属性，如下所示。

   "docker.host":"tcp://localhost:23750"

3. 从本地终端 / PowerShell 运行以下命令（将 user@hostname 替换为远程用户和服务器的主机名 / IP）。

   ssh -NL localhost:23750:/var/run/docker.sock user@hostname

VS Code 现在将能够附加到远程主机上任何正在运行的容器。你也可以使用专门的、本地的 devcontainer.json 文件来创建 / 连接到远程 dev 容器。

一旦你完成了，在终端 / PowerShell 中按 Ctrl+C 关闭隧道。

注意：如果 ssh 命令失败，你可能需要在你的 SSH 主机上允许 StreamLocalForwarding。

1. 在 SSH 主机上（不是本地）用编辑器（如 Vim、nano 或 Pico）打开 / etc/ssh/sshd_config。
2. 添加设置 AllowStreamLocalForwarding yes。
3. 重启 SSH 服务器（在 Ubuntu 上，运行 sudo systemctl restart sshd）。
4. 重试。

容器的高级配置技巧 #。

请参阅高级容器配置文章，了解有关以下主题的信息。

• 添加环境变量
• 添加另一个本地文件挂载
• 改变或删除默认的源代码挂载
• 提高容器的磁盘性能
• 为你的开发容器添加一个非 root 用户
• 避免在容器重建时重新安装扩展程序
• 为 Docker Compose 设置项目名称
• 从容器内部使用 Docker 或 Kubernetes
• 一次性连接到多个容器
• 在远程 Docker 机器或 SSH 主机上的容器内开发
• 减少 Docker 文件的构建警告

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

选择 Remote 使用的发行版 - WSL

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

要打开一个非默认的发行版，请从要使用的发行版的 WSL 外壳中运行代码. 或使用 Remote-WSL：新窗口使用发行版。

对于比 Windows 10、2019 年 5 月更新（版本 1903）更早的 WSL 版本，WSL 命令只能使用默认发行版。由于这个原因，如果你同意改变默认的发行版，Remote-WSL 可能会提示你。

你可以随时使用 wslconfig.exe 来改变你的默认。

比如说。

wslconfig /setdefault Ubuntu

你可以通过运行查看你已经安装了哪些发行版。

wslconfig /l

配置服务器的启动环境 #。

当远程 WSL 扩展在 WSL 中启动 VS Code 服务器时，它不会运行任何外壳配置脚本。这样做是为了避免自定义的配置脚本会妨碍启动。

如果你需要配置启动环境，你可以使用这里描述的环境设置脚本。

为远程扩展主机 #配置环境

远程扩展主机和终端的环境是基于默认 shell 的配置脚本。为了评估远程扩展主机进程的环境变量，服务器创建了一个默认 shell 的实例作为交互式登录 shell。它从其中探测环境变量，并将其作为远程扩展主机进程的初始环境。因此，环境变量的值取决于什么 shell 被配置为默认的以及该 shell 的配置脚本的内容。

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

要改变 WSL 发行版的默认外壳，请按照这篇博文的指示。

修复代码命令不工作的问题

如果在 Window 上从 WSL 终端输入代码不能工作，因为找不到代码，你可能在 WSL 的 PATH 中缺少一些关键位置。

通过打开 WSL 终端并输入 echo $PATH 来检查。你应该看到列出了 VS 代码的安装路径。在默认情况下，这将是。

/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"

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

用 “代码” 命令 #查找问题

如果在 Windows 命令提示符下输入 code 不能启动 VS Code，你可以通过运行 VSCODE_WSL_DEBUG_INFO=true code 来帮助我们诊断问题。

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

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

当 WSL 窗口无法连接到远程服务器时，你可以在 WSL 日志中获得更多信息。在提交问题时，一定要发送 WSL 日志的全部内容。

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

要想获得更多粗略的日志记录，请在用户设置中启用 remote.WSL.debug 设置。

服务器启动失败，出现分段故障 #。

你可以给我们发送核心转储文件，帮助我们调查这个问题。要获得核心转储文件，请遵循以下步骤。

在 Windows 命令提示符下。

• 运行代码 — 定位 - extension ms-vscode-remote.remote-wsl 以确定 Remote-WSL 扩展文件夹。
• cd 到返回的路径。
• 用 VS 代码打开 wslServer.sh 脚本，代码.\scripts\wslServer.sh。
• 在最后第三行（在 export VSCODE_AGENT_FOLDER=”DATAFOLDER” 之前），添加 ulimit -C unlimited。
• 启动运行远程服务器的 Remote-WSL 窗口，等待分段故障。

核心文件将在上面的 Remote-WSL 扩展文件夹中。

我看到 EACCESS：试图在打开的工作区重命名一个文件夹时出现权限拒绝错误 #。

这是 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），你可以使用输入选项。

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/libexec/git-core/git-credential-wincred.exe"

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

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

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

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

GitHub Codespaces 提示

关于 GitHub Codespaces 的提示和问题，请参阅 GitHub Codespaces 文档。你也可以查看可能影响你的 Codespaces 的已知网络限制和调整。

扩展提示

虽然许多扩展可以不加修改地工作，但有一些问题会使某些功能无法按预期工作。在某些情况下，你可以使用另一个命令来解决这个问题，而在其他情况下，扩展可能需要被修改。本节为常见的问题和解决这些问题的提示提供快速参考。你也可以参考关于支持远程开发的主要扩展文章，了解关于修改扩展以支持远程扩展主机的深入指南。

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

一些扩展依赖的库在某些 WSL Linux 发行版的基本安装中找不到。你可以通过使用你的 Linux 发行版的软件包管理器来添加额外的库。对于基于 Ubuntu 和 Debian 的发行版，运行 sudo apt-get install 来安装需要的库。检查你的扩展或错误信息中提到的运行时的文档，了解更多的安装细节。

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

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

解决方法。你可以在连接到远程端点后，通过运行偏好设置来设置端点的具体设置。打开远程设置 “命令调色板（F1）或在” 设置 “编辑器中选择” 远程 “ 选项卡。这些设置将覆盖你在连接时的任何本地设置。

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

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

解决方法。一旦你连接到 SSH 主机、容器或 WSL，你就可以按照本地的方式安装 VSIX。运行扩展程序。从 VSIX 安装… 命令，从命令调色板（F1）。您可能还想在 settings.json 中添加 “extensions.autoUpdate”: false，以防止自动更新到最新的 Marketplace 版本。关于在远程环境下开发和测试扩展的更多信息，请参见支持远程开发。

浏览器不在本地打开

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

解决方法。扩展可以使用 vscode.env.openExternal API 来解决这个问题。详情请见扩展的作者指南。

剪贴板不起作用 #。

一些扩展使用 clipboardy 等节点模块与剪贴板集成。不幸的是，这可能会导致扩展在远程端与剪贴板的整合不正确。

解决方法。该扩展可以切换到 VS Code 剪贴板 API 来解决这个问题。详情请看扩展的作者指南。

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

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

解决方法。扩展可以使用 vscode.env.openExternal 或 vscode.env.asExternalUri APIs（自动转发本地主机端口）来解决这个问题。详情见扩展作者指南。作为一种变通方法，使用转发端口命令来手动进行。

网页视图的内容没有出现

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

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

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

被阻止的本地主机端口

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

解决方法。VS Code 1.40 引入了一个新的 vscode.env.asExternalUri API，供扩展程序以编程方式转发任意的端口。详情请看扩展作者的指南。作为一种解决方法，你可以使用转发端口命令来手动完成。

储存扩展数据的错误

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

解决方法。扩展可以使用 context.globalStoragePath 或 context.storagePath 属性来解决这个问题。详情见扩展作者指南。

无法登录 / 每次连接到新的端点都要登录

需要登录的扩展可能会使用他们自己的代码来坚持秘密。这段代码可能会因为缺少依赖关系而失败。即使它成功了，秘密也会被远程存储，这意味着你必须为每个新的端点登录。

解决方法。扩展可以使用 keytar 节点模块来解决这个问题。详情见扩展作者指南。

一个不兼容的扩展使 VS Code 无法连接 #。

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

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

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 for VS Code stable 和 / 或 rm -rf ~/.vscode-server-insiders/extensions for 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，由于 libc 在 Alpine Linux（musl）和其他发行版（glibc）中的实现方式存在根本差异，所包含的本地代码或运行时可能无法工作。

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

因模块缺失而导致扩展失败 #。

依赖于 Electron 或 VS Code 基础模块（不由扩展 API 暴露）而不提供回退的扩展在远程运行时可能会失败。你可能会在开发工具控制台中看到错误，如找不到原始 fs。

解决方法。删除对 Electron 模块的依赖，或者提供一个回退。详情请看扩展的作者指南。

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

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

解决方法。如果你创建了一个旨在本地运行的 “UI” 扩展，你可以使用 vscode.workspace.fs API 来与远程工作区文件系统进行交互。然后你可以把它作为你的 “工作区” 扩展的一个依赖项，并在需要时使用命令来调用它。关于不同类型的扩展以及如何使用命令在它们之间进行通信的细节，请参见扩展作者的指南。

不能从扩展中访问附加设备

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

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

问题和反馈

报告问题

如果你遇到一个远程开发扩展的问题，收集正确的日志是很重要的，这样我们就能帮助诊断你的问题了。

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

你可以用 Remote-SSH: Show Log from the Command Palette (F1) 来获取远程 - SSH 扩展的日志。当报告 Remote - SSH 问题时，也请确认你是否能够从外部终端（不使用 Remote - SSH）SSH 进入你的机器。

同样地，你可以用 Remote-Containers 获得 Remote - Containers 扩展日志。显示日志。

和上面两个一样，你可以通过 Remote WSL: Show Log 获得 Remote - WSL 的日志。还可以检查你的问题是否在 WSL repo 的上游被跟踪（而不是由于 Remote - WSL 扩展引起的）。

如果你在远程使用其他扩展时遇到问题（例如，其他扩展在远程环境下不能正常加载或安装），从远程扩展主机输出通道（输出：关注输出视图）中抓取日志，并从下拉菜单中选择日志（远程扩展主机），会很有帮助。

注意：如果你只看到日志（扩展主机），这是本地扩展主机，而远程扩展主机没有启动。这是因为只有在创建了日志文件之后才会创建日志通道，所以如果远程扩展主机没有启动，远程扩展主机的日志文件就没有被创建，也不会显示在输出视图中。这仍然是有用的信息，可以包括在你的问题中。

远程问题和反馈资源

我们有各种其他的远程资源。

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

10/7/2021
https://code.visualstudio.com/docs/remote/troubleshooting#_configuring-key-based-authentication