远程开发技巧

本文介绍了每个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提交， 将以 VS Code 打开文件，而非默认的终端编辑器（如Vim或纳米).

配置基于密钥的认证

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

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

快速入门：使用 SSH 密钥

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

创建本地SSH密钥对

检查一下你本地机器上是否已经有SSH密钥。这通常位于~/.ssh/id_ed25519.pub在macOS / Linux上，以及.嘘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 <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")'"
    

    你可能想验证authorized_keys文件.嘘你在SSH主机上为远程用户设置的文件夹属于你，没有其他用户有权限访问。详情请参见OpenSSH维基。

授权你的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`" `""
    

    验证authorized_keys文件.嘘你在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还是归档吧。

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\\我的\\id_ed25519.

重用PuTTYGen生成的密钥

如果你用 PuTTYGen 为你连接的主机设置了 SSH 公钥认证，你需要转换你的私钥，这样其他 SSH 客户端才能使用它。具体做法：

1. 本地打开PuTTYGen，加载你想转换的私钥。

2. 在应用菜单中选择转换>导出 OpenSSH 密钥。将转换后的密钥保存到本地位置，以下为.嘘用户配置文件文件夹中的目录（例如）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
   

提升多用户服务器的安全

远程 - SSH 扩展负责安装和维护“VS Code Server”。服务器启动时会随机生成一个密钥，任何新连接服务器都需要提供密钥。密钥存储在远程用户的磁盘上，只有当前用户能读取。在/版本.

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

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

配置方法：

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

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

   

3. 如果你已经连接到SSH主机，请从命令面板（F1）中选择远程SSH：关闭主机上的代码服务器......这样该设置就会生效。

如果连接时遇到错误，可能需要在SSH主机的sshd配置中启用套接字转发。具体做法：

1. 开门/等等/嘘/sshd_config在 SSH 主机上的文本编辑器（如 vi、nano 或 pico）中（非本地）。
2. 添加设置允许StreamLocalForwarding，是的.
3. 重启SSH服务器。（在Ubuntu上，跑sudo systemctl restart sshd.).
4. 重试。

排查连接挂机或故障

如果你在连接时遇到VS Code卡住（甚至超时）的问题，有几种方法可以尝试解决。

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

一个有助于排查各种远程SSH问题的命令是“远程SSH：在主机上终止VS代码服务器”。这会移除服务器，这可以修复你可能看到的各种问题和错误信息，比如“无法建立连接server_name：VS代码服务器未能启动。”

看看VS Code是否在等待提示

启用偏远。SSH.show登录终端 在VS Code中设置并重试。如果提示输入密码或令牌，请参见“启用替代SSH认证方法”，了解减少提示频率的详细信息。

如果仍然有困难，请在settings.json并重试：

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

绕过某些Windows OpenSSH服务器版本的漏洞

由于某些版本的 OpenSSH 服务器存在漏洞，默认检查主机是否运行 Windows 的作可能无法正常工作。而 Windows 1909 及以下版本的 OpenSSH 服务器则不会出现这种情况。

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

"remote.SSH.useLocalServer": false

你也可以使用以下属性强制 VS Code 将特定主机标识为 Windows：

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

修复已经合并，因此这个问题应该会在高于 8.1.0.0 版本的服务器中解决。

在远程主机上启用TCP转发

远程——SSH扩展利用SSH隧道促进与主机的通信。在某些情况下，你的SSH服务器可能会禁用这个功能。要确认是否是这个问题，请在输出窗口打开“远程-SSH”类别，检查以下消息：

open failed: administratively prohibited: open failed

如果你看到那个提示，请按照以下步骤更新你的SSH服务器的sshd配置：

1. 开门/等等/嘘/sshd_config或C：\ProgramData\ssh\sshd_config在 SSH 主机上的文本编辑器（如 Vim、nano、Pico 或 Notepad）中进行（本地不存在）。
2. 添加设置允许Tcp转发，是的.
3. 重启SSH服务器。（在Ubuntu上，跑sudo systemctl restart sshd.在Windows上，在管理员PowerShell运行中，Restart-Service sshd).
4. 重试。

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

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

确保远程机器有互联网访问权限

远程机器必须有互联网接入，才能从 Marketplace 下载 VS Code 服务器及其扩展。有关连接需求的详细信息，请参见常见问题解答。

在远程主机上设置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 会把安装脚本写到系统临时目录，并尝试从那里执行。你可以和系统管理员合作，看看是否可以绕过这个问题。

检查安装时是否启用了不同的外壳

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

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

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

一个解决方法是使用控制大师OpenSSH 中的选项（仅限 macOS/Linux 客户端），详见“启用替代 SSH 认证方法”，使 VS Code 的两条连接通过单一 SSH 连接复用到同一节点。

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

SSH 是一种非常灵活的协议，支持多种配置。如果你在登录终端或远程SSH输出窗口看到其他错误，可能是缺少某个设置。

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

要访问配置文件，请在命令面板（F1）中运行Remote-SSH： Open Configuration File。然后你可以和管理员一起添加必要的设置。

启用替代SSH认证方法

如果你连接的是SSH远程主机，并且符合以下条件：

• 连接双因素认证
• 使用密码认证
• 当SSH代理未运行或不可访问时，使用带有密码短语的SSH密钥

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

如果你仍然遇到困难，可能需要添加以下房产settings.json并重试：

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

如果你在macOS和Linux上，想减少输入密码或令牌的频率，你可以启用控制大师在你的本地机器上，使 OpenSSH 能够在单一连接上运行多个 SSH 会话。

以实现控制大师:

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环境中访问，请执行ssh-add -l在本地VS Code窗口的终端中。你应该会在代理中看到密钥列表（或者提示没有密钥）。如果代理未运行，请按照以下说明启动。启动代理后，务必重启 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扩展连接到你选择的远程系统，而不会反复提示输入密码，但像Git这样的远程工具无法访问你本地解锁的私钥。

你可以通过打开遥控器的集成终端并运行来看到这一点ssh-add -l.该命令本应列出已解锁的密钥，但实际上却报告无法连接认证代理的错误。背景设定ForwardAgent，是的使本地SSH代理在远程环境中可用，解决了这一问题。

你可以通过编辑你的.ssh/config文件（或者其他什么）Remote.SSH.configFile设置为 - 使用 Remote-SSH： Open SSH 配置文件......确认命令）并添加：

Host *
    ForwardAgent yes

注意你可能想更严格，只为特定命名主机设置选项。

修复SSH文件权限错误

SSH对文件权限可能非常严格，如果设置错误，你可能会看到诸如“警告：未受保护的私钥文件！”这样的错误。有几种方法可以更新文件权限以解决这个问题，具体将在下文章节中介绍。

本地SSH文件和文件夹权限

macOS / Linux：

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

Windows：

具体的预期权限可能会根据你使用的具体SSH实现而有所不同。我们建议使用开箱即用的Windows 10 OpenSSH客户端。

在这种情况下，确保所有文件.嘘你在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 安装路径中。你也可以通过添加偏远。SSH.path属性到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 安装 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 图形用户界面。

要使用命令行，请从本地终端（替换）执行以下命令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

这样你在远程机器上的主文件夹就会在~/嘘.完成后，你可以使用作系统的Finder/文件资源管理器卸载，或者使用命令行：

umount "$HOME/sshfs/$USER_AT_HOST"

Windows：

请按照以下步骤作：

1. 在 Linux 上，添加.gitattributes文件添加到你的项目中，以强制Linux和Windows之间保持一致的行尾，以避免因两作系统之间CRLF/LF差异带来的意外问题。详情请参见解决 Git 行尾问题。

2. 接下来，使用 Chocolatey 安装 SSHFS-Win：Choco安装SSHFS

3. 安装了Windows版SSHFS后，你可以使用文件资源管理器的地图网络驱动器......选项，路径\\sshfs\user@hostname， 其中user@hostname是你的远程用户，是主机名/IP。你可以用命令提示符来编写脚本，具体如下：网络使用 /PERSISTENT：NO X： \\shfs\user@hostname

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

从终端连接到远程主机

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

例如，要连接到remote_server并打开/代码/my_project文件夹，运行：

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

我们需要猜测输入路径是文件还是文件夹。如果它有文件扩展名，则被视为文件。

要强制打开文件夹，可以在路径上添加斜杠，或者使用：

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

要强制打开文件，添加——去或使用：

code --file-uri vscode-remote/ssh-remote+remote_server/code/fileWithoutExtension

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

使用 SSHFS 访问远程文件的另一种方法是用途rsync将远程主机上文件夹的全部内容复制到你的本地机器上。该rsync命令会决定每次运行时需要更新哪些文件，这比使用类似的程序更高效、更方便SCP或SFTP.如果你真的需要使用多文件或高性能的本地工具，这主要是需要考虑的。

该rsynccommand 在 macOS 上开箱即用，可以通过 Linux 包管理器安装（例如sudo apt-get 安装 rsync在Debian/Ubuntu上）。对于Windows，你需要使用WSL或Cygwin来访问该命令。

使用该命令时，先导航到你想存储同步内容的文件夹，然后执行以下替换程序user@hostname远程用户和主机名/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 服务器

SSH 扩展提供了一个命令，用于从远程机器中清理 VS Code 服务器，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 扩展时遇到困难，觉得需要提交问题，首先确保你已经阅读了本站的文档，然后查看故障排除维基文档，了解如何获取日志文件并尝试更多步骤，帮助缩小问题根源。

开发容器技巧

如果你想了解使用开发容器的技巧，可以访问开发容器技巧与窍门。

WSL小技巧

首次开始：VS Code Server 的先决条件

一些WSL Linux发行版缺少VS Code服务器启动所需的库。你可以通过它的包管理器为你的 Linux 发行版添加额外的库。

Debian和Ubuntu

打开Debian或Ubuntu WSL外壳来添加WGET以及CA证书:

sudo apt-get update && sudo apt-get install wget ca-certificates

阿尔卑斯

将阿尔卑斯山的WSL壳体作为根打开（wsl -d Alpine -u 根）补充libstdc++:

apk update && apk add libstdc++

在 Windows 10 2018 年 4 月更新（版本 1803 及更早版本）上，/垃圾/砰要求：

apk update && apk add bash

选择WSL扩展所使用的分布

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

要打开非默认发行版，请执行代码。从发行版的 WSL 壳中切换到使用或使用 WSL： New Window 使用发行版。

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

你总可以用wslconfig.exe来更改默认设置。

例如：

wslconfig /setdefault Ubuntu

你可以通过运行以下程序查看你安装了哪些发行版：

wslconfig /l

配置服务器启动环境

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

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

为远程分机主机配置环境

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

有关每个shell配置脚本的概述，请参见Unix壳初始化。大多数WSL发行版/垃圾/砰配置为默认 shell。/垃圾/砰我会在下面找启动文件/etc/个人资料首先，以及所有启动文件~/.bash_profile,~/.bash_login,~/.个人资料.

要更改WSL发行版的默认外壳，请按照这篇博客文章的说明作。

修复代码命令无法使用的问题

如果正在打字代码在 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="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命令提示符无法启动VS Code，你可以通过运行来帮助我们诊断问题VSCODE_WSL_DEBUG_INFO=真码。.

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

发现启动或连接服务器时出现问题

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

通过运行命令 WSL： Open Log 打开 WSL 日志。日志会显示在终端视图的WSL标签下。

如果想获得更详细的日志记录，请启用以下设置偏远。WSL.调试在用户设置里。

服务器启动失败时发生了分段故障

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

在Windows命令提示符中：

• 执行Code --locate-extension MS-VSoDEod-remote.Remote-WSL以确定WSL扩展文件夹。
• CD回到被回归的道路上。
• 打开wslServer.sh带有 VS Code 的脚本，代码 .\scripts\wslServer.sh.
• 在最后一句之前（在之前）“$VSCODE_REMOTE_BIN/$COMMIT/bin/$SERVER_APPNAME” “$@”），添加ulimit -C 无限.
• 启动运行远程服务器的WSL窗口，等待分段错误。

核心文件会放在上面的WSL扩展文件夹里。

我看到 EACCES：权限被拒绝，尝试在开放工作区中重命名文件夹

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

为了避免这个问题，设置偏远。WSL.fileWatcher.polling真是太真实了。然而，基于轮询的系统对大型工作区的性能有影响。

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

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运行以下作来配置凭证管理器：

    git config --global credential.helper wincred
   

2. 配置WSL使用相同的凭证辅助工具，但在WSL终端中运行以下内容：

    git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
   

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

在从 WSL 进行 Git 推送或同步时，解决会卡顿

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

要么用无密码的SSH密钥，要么用HTTPS克隆，要么直接运行Git 推送从命令行开始绕过这个问题。

GitHub Codespaces 技巧

有关GitHub Codespaces的提示和问题，请参见GitHub Codespaces文档。你还可以查看已知的网络限制和可能影响代码空间的适应措施。

延伸技巧

虽然许多扩展无需修改即可正常工作，但也有一些问题可能阻碍某些功能正常工作。在某些情况下，你可以用其他命令来绕过这个问题，而在另一些情况下，扩展可能需要修改。本节提供了常见问题的快速参考及解决建议。您也可以参考主扩展文章《支持远程开发》，其中包含关于如何修改扩展以支持远程扩展主机的深入指南。

解决关于缺失依赖的错误

部分扩展依赖于某些 WSL Linux 发行版基础安装中没有的库。你可以通过它的包管理器为你的 Linux 发行版添加额外的库。对于基于Ubuntu和Debian的发行版，运行sudo apt-get install <package>安装所需的库。请查看你扩展的文档或错误提示中提到的运行时文件，获取更多安装细节。

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

VS Code 的本地用户设置在连接远程终端时会被重复使用。虽然这样可以保持用户体验的一致性，但由于目标位置不同，你可能需要在本地机器和每个主机/容器/世界运行平台之间调整绝对路径设置。

解决方案：连接远程端点后，你可以通过命令面板中的“偏好设置：打开远程设置”命令（F1）或在设置编辑器中选择远程标签来设置特定端点的设置。这些设置会覆盖你连接时本地设置。

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

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

解决方案：一旦你连接到了SSH主机、容器或WSL，就可以像本地安装VSIX一样。运行扩展：从VSIX安装......命令面板（F1）中的命令。你也可以补充一些“extensions.autoUpdate”： false到settings.json以防止自动更新到最新的市场版本。有关在远程环境中开发和测试扩展的更多信息，请参见支持远程开发。

浏览器无法在本地打开

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

解决方案：扩展可以使用vscode.env.openExternalAPI来解决这个问题。详情请参见扩展作者指南。

剪贴板不工作

一些扩展使用节点模块，如剪贴板可以和剪贴板集成。不幸的是，这可能导致扩展程序错误地与远程端的剪贴板集成。

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

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

在容器、SSH主机或GitHub Codespaces中运行时，浏览器连接的端口可能会被阻止。

分辨率：扩展可以使用vscode.env.openExternal或vscode.env.asExternalUriAPI（自动转发本地主机端口）来解决这个问题。详情请参见扩展作者指南。作为变通方法，可以用“向前转端口”命令手动作。

网页浏览内容未显示

如果扩展的网页视图内容使用iframe要连接到本地的网页服务器，Webview 连接的端口可能会被阻挡。此外，如果扩展硬编码VScode-resource：//用 URI 代替使用作为WebviewUri，内容可能不会出现在Codespaces浏览器编辑器中。

解决方案：扩展可以使用webview.asWebviewUri解决与VScode-resource：//上呼吸道。

如果端口被阻挡，最佳方法是使用 webview 消息传递 API。作为一个变通办法，vscode.env.asExternalUri可以使用 WebView 连接到 VS Code 生成的本地主机 Web 服务器。然而，目前仅在 Codespaces 浏览器编辑器中，MicrosoftDocs/vscodespaces#11 阻止了此功能。有关变通方法的详细信息，请参见扩展作者指南。

被封锁的本地主机端口

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

分辨率：VS 代码 1.40 引入了新的vscode.env.asExternalUriAPI，用于程序化转发任意端口的扩展。详情请参见扩展作者指南。作为变通方法，您可以使用“转发端口”命令手动转发端口。

存储扩展数据的错误

扩展可能会尝试通过寻找~/.config/CodeLinux上的文件夹。这个文件夹可能不存在，这可能导致扩展出现像这样的错误ENOENT：没有这样的文件或目录，打开'/root/.config/Code/User/filename-goes-here.

分辨率：扩展可以使用context.globalStorageUri或context.storageUri用属性来解决这个问题。详情请参见扩展作者指南。

每次连接新终端都无法登录/必须登录

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

解决方法：扩展可以使用 SecretStorage API 来解决这个问题。详情请参见扩展作者指南。

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

如果在远程主机、容器或WSL中安装了不兼容的扩展，我们见过VS Code服务器因不兼容而卡顿或崩溃的情况。如果扩展立即激活，可能会阻止你连接并卸载扩展。

解决方法：手动删除远程扩展文件夹，步骤如下：

1. 对于容器，确保你的devcontainer.json不再包含对故障延长线的提及。

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

   • 如果是SSH或WSL，则相应地连接到环境（运行嘘连接服务器或打开WSL终端）。
   • 如果使用容器，通过调用来识别容器 IDDocker PS -a并且在列表中查找带有正确名称的图片。如果容器被停止，运行Docker run -it <id> /bin/sh. 如果它在运行，就跑Docker exec -it <id> /bin/sh.

3. 连接好后，赶紧跑rm -rf ~/.vscode-server/extensionsVS Code 稳定和/或rm -rf ~/.vscode-server-insiders/extensionsVS Code Insiders 可以移除所有扩展。

发布或购买预构建的原生模块的扩展会失败

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

分辨率：扩展需要修改以解决这个问题。它们需要包含（或动态获取）VS Code所发布的“模块”Node.js版本的两组二进制（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 中实现 （Musl）以及其他分布（格利比克).

解决方案：扩展用户需要选择支持这些平台，通过编译/包含这些额外目标的二进制文件来支持。需要注意的是，一些第三方 npm 模块可能包含可能导致此问题的原生代码。因此，在某些情况下，你可能需要与 npm 模块作者合作，添加额外的编译目标。详情请参见扩展作者指南。

扩展因缺失模块而失败

依赖Electron或VS Code基础模块（扩展API未提供备份）且不提供备份的扩展，在远程运行时可能会失败。你可能会在开发者工具控制台看到类似的错误原始FS找不到。

解决方案：去除对电子模块的依赖，或者提供一个后备方案。详情请参见扩展作者指南。

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

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

解决方案：如果你创建一个本地运行的“UI”扩展，你可以使用vscode.workspace.fsAPI用于与远程工作区文件系统交互。然后你可以把它设为“工作区”扩展的依赖，并根据需要用命令调用它。有关不同类型扩展的详细信息及如何使用命令在它们之间通信，请参阅扩展作者指南。

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

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

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

问题与反馈

报告问题

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

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

你可以用命令面板（F1）中的 Remote-SSH： Show Log 获取 Remote - SSH 扩展日志。在报告远程-SSH问题时，请确认你是否能从外部终端（不使用远程-SSH）连接到你的机器。

同样，你也可以用 Dev Containers： Show Container Log 获取 Dev Containers 扩展日志。

和上面两个一样，你也可以用WSL：显示日志获取WSL扩展日志。还要检查你的问题是否在WSL仓库的上游被追踪（而不是WSL扩展导致的）。

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

注意：如果你只看到日志（扩展主机），那就是本地扩展主机，远程扩展主机没有启动。这是因为日志通道是在日志文件创建后才创建的，如果远程扩展主机未启动，那么远程扩展主机的日志文件也未被创建，输出视图中也未显示。这些信息仍然很有帮助，值得你在问题中加入。

远程提问和反馈资源

我们还有多种其他远程资源：

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