遠端開發技巧

本文件涵蓋了 Visual Studio Code 遠端開發擴充套件的故障排除技巧。有關每個特定擴充套件的設定和使用方法，請參閱 SSH、Containers 和 WSL 文章。或者嘗試入門 教程，幫助您快速在遠端環境中執行。

有關 GitHub Codespaces 的技巧和問題，請參閱 GitHub Codespaces 文件。

SSH 技巧

SSH 功能強大且靈活，但也帶來了一些設定複雜性。本節包含了一些在不同環境中設定和使用 Remote - SSH 擴充套件的技巧。

自定義 AI 聊天響應

自定義指令使您能夠描述通用指南或規則，以獲得符合您特定編碼實踐和技術棧的響應。

您可以使用自定義指令向 Copilot 提供有關您連線的遠端環境型別（例如安裝了哪些語言或工具鏈）的更多資訊。您可以像在本地一樣使用 copilot-instructions.md 檔案。在使用開發容器時，您還可以執行 額外的指令配置步驟。

配置 $EDITOR 變數

對於 macOS / Linux 遠端主機，請將此程式碼片段新增到您的 shell 配置檔案（如 .bashrc 或 .zshrc）中

if [ "$VSCODE_INJECTION" = "1" ]; then
    export EDITOR="code --wait" # or 'code-insiders' if you're using VS Code Insiders
fi

對於 Windows 主機，這裡是等效的 PowerShell 命令

if ($env:VSCODE_INJECTION -eq "1") {
    $env:EDITOR = "code --wait"  # or 'code-insiders' for VS Code Insiders
}

現在，執行使用 $EDITOR 變數的終端命令（如 git commit）將會在 VS Code 中開啟檔案，而不是預設的基於終端的編輯器（如 vim 或 nano）。

配置基於金鑰的身份驗證

SSH 公鑰身份驗證是一種方便、高安全性的身份驗證方法，它結合了本地“私鑰”和一個與您在 SSH 主機上的使用者帳戶關聯的“公鑰”。本節將指導您如何生成這些金鑰並將其新增到主機。

提示： PuTTY for Windows 不是受支援的客戶端，但您可以轉換 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 Server，並且使用者屬於管理員組

    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 Server，並且使用者屬於管理員組

    $USER_AT_HOST="your-user-name-on-host@hostname"
    $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
    
    Get-Content "$PUBKEYPATH" | Out-String | ssh $USER_AT_HOST "powershell `"Add-Content -Force -Path `"`$Env:PROGRAMDATA\ssh\administrators_authorized_keys`" `""
    

  • 否則

    $USER_AT_HOST="your-user-name-on-host@hostname"
    $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
    
    Get-Content "$PUBKEYPATH" | Out-String | ssh $USER_AT_HOST "powershell `"New-Item -Force -ItemType Directory -Path `"`$HOME\.ssh`"; Add-Content -Force -Path `"`$HOME\.ssh\authorized_keys`" `""
    

    驗證**遠端 SSH 主機上**的 .ssh 資料夾中的 authorized_keys 檔案是否由您擁有，並且沒有其他使用者有權訪問它。有關詳細資訊，請參閱 OpenSSH wiki。

透過專用金鑰提高安全性

雖然跨所有 SSH 主機使用單個 SSH 金鑰可能很方便，但如果有人獲得了對您的私鑰的訪問許可權，他們將能夠訪問您的所有主機。您可以透過為您的開發主機建立單獨的 SSH 金鑰來防止這種情況。只需按照以下步驟操作

1. 在不同的檔案中生成單獨的 SSH 金鑰。

   macOS / Linux：在**本地終端**中執行以下命令

   ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519-remote-ssh
   

   Windows：在**本地 PowerShell** 中執行以下命令

   ssh-keygen -t ed25519 -f "$HOME\.ssh\id_ed25519-remote-ssh"
   

2. 按照快速入門中的相同步驟在 SSH 主機上授權金鑰，但將 PUBKEYPATH 設定為 id_ed25519-remote-ssh.pub 檔案。

3. 在 VS Code 中，在命令面板（F1）中執行 **Remote-SSH: Open Configuration File...**，選擇一個 SSH 配置檔案，然後按如下方式新增（或修改）主機條目

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

   提示：您也可以為 Windows 路徑使用 /。如果使用 \，您將需要使用兩個斜槓。例如，C:\\path\\to\\my\\id_ed25519。

重複使用 PuTTYGen 生成的金鑰

如果您使用 PuTTYGen 為您正在連線的主機設定 SSH 公鑰身份驗證，則需要轉換您的私鑰，以便其他 SSH 客戶端可以使用它。為此

1. 在**本地**開啟 PuTTYGen 並載入您要轉換的私鑰。

2. 從應用程式選單中選擇 **Conversions > Export OpenSSH key**。將轉換後的金鑰儲存到您使用者配置檔案資料夾中的 .ssh 目錄下的**本地**位置（例如 C:\Users\youruser\.ssh）。

3. 驗證此新的**本地**檔案由您擁有，並且沒有其他使用者有權訪問它。

4. 在 VS Code 中，在命令面板（F1）中執行 **Remote-SSH: Open Configuration File...**，選擇您要更改的 SSH 配置檔案，然後在配置檔案中按如下方式新增（或修改）主機條目以指向該檔案

   Host name-of-ssh-host-here
       User your-user-name-on-host
       HostName host-fqdn-or-ip-goes-here
       IdentityFile ~/.ssh/exported-keyfile-from-putty
   

提高多使用者伺服器的安全性

Remote - SSH 擴充套件會安裝和維護“VS Code Server”。該伺服器使用隨機生成的金鑰啟動，任何對該伺服器的新連線都需要提供該金鑰。金鑰儲存在遠端磁碟上，只能由當前使用者讀取。有一個 HTTP 路徑在沒有身份驗證的情況下可用，即 /version。

預設情況下，伺服器監聽 localhost 上的隨機 TCP 埠，然後將其轉發到您的本地機器。如果您連線到 **Linux 或 macOS** 主機，您可以切換到使用限制為特定使用者的 Unix 套接字。然後將轉發此套接字而不是埠。

注意：此設定**停用連線多路複用**，因此建議配置公鑰身份驗證。

配置方法

1. 確保您在 Windows、macOS 或 Linux 上擁有**本地 OpenSSH 6.7+ SSH 客戶端**，以及**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 Server 某些版本的 bug

由於 Windows 某些版本的 OpenSSH Server 中存在 bug，用於確定主機是否執行 Windows 的預設檢查可能無法正常工作。Windows 1909 及更低版本附帶的 OpenSSH Server 不存在此問題。

幸運的是，您可以透過在 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 文章來了解其用法示例。

確保遠端計算機具有 Internet 訪問許可權

遠端計算機必須具有 Internet 訪問許可權才能從 Marketplace 下載 VS Code Server 和擴充套件。有關連線要求的詳細資訊，請參閱 FAQ。

在遠端主機上設定 HTTP_PROXY / HTTPS_PROXY

如果您的遠端主機位於代理伺服器後面，您可能需要在**SSH 主機**上設定 HTTP_PROXY 或 HTTPS_PROXY 環境變數。開啟您的 ~/.bashrc 檔案，新增以下內容（將 proxy.fqdn.or.ip:3128 替換為適當的主機名/IP 和埠）

export HTTP_PROXY=http://proxy.fqdn.or.ip:3128
export HTTPS_PROXY=$HTTP_PROXY

# Or if an authenticated proxy
export HTTP_PROXY=http://username:password@proxy.fqdn.or.ip:3128
export HTTPS_PROXY=$HTTP_PROXY

解決 /tmp 掛載了 noexec 的問題

某些遠端伺服器被設定為不允許從 /tmp 執行指令碼。VS Code 將其安裝指令碼寫入系統臨時目錄並嘗試從那裡執行。您可以與系統管理員協商以確定是否可以解決此問題。

檢查安裝過程中是否啟動了不同的 shell

有些使用者會在其 .bash_profile 或其他啟動指令碼中啟動一個不同的 shell，因為他們想使用與預設 shell 不同的 shell。這可能會破壞 VS Code 的遠端伺服器安裝指令碼，不建議這樣做。而是使用 chsh 命令更改遠端計算機上的預設 shell。

連線到動態分配每連線機器的系統

某些系統會在每次建立 SSH 連線時動態地將連線路由到一個叢集節點。這對 VS Code 來說是個問題，因為它會建立兩次連線來開啟遠端視窗：第一次是為了安裝或啟動 VS Code Server（或查詢已執行的例項），第二次是為了建立 VS Code 用於與伺服器通訊的 SSH 埠隧道。如果 VS Code 在建立第二次連線時被路由到不同的機器，它將無法與 VS Code 伺服器通訊。

一種解決方法是使用 OpenSSH 的 ControlMaster 選項（僅限 macOS/Linux 客戶端），在啟用備用 SSH 身份驗證方法中進行了描述，這樣 VS Code 的兩次連線將透過到同一節點的單個 SSH 連線進行多路複用。

聯絡您的系統管理員獲取配置幫助

SSH 是一個非常靈活的協議，支援多種配置。如果您在登入終端或 **Remote-SSH** 輸出視窗中看到其他錯誤，可能是由於缺少設定。

請聯絡您的系統管理員，瞭解您的 SSH 主機和客戶端所需的設定。連線到您的 SSH 主機的特定命令列引數可以新增到 SSH 配置檔案中。

要訪問您的配置檔案，請在命令面板（F1）中執行 **Remote-SSH: Open Configuration File...**。然後，您可以與管理員一起新增必要的設定。

啟用備用 SSH 身份驗證方法

如果您連線到 SSH 遠端主機並且

• 使用雙因素身份驗證進行連線
• 使用密碼身份驗證
• 使用帶密碼短語的 SSH 金鑰，而 SSH Agent 未執行或不可用

那麼 VS Code 應該會自動提示您輸入所需資訊。如果您沒有看到提示，請在 VS Code 中啟用 remote.SSH.showLoginTerminal 設定。此設定會在 VS Code 執行 SSH 命令時顯示終端。然後，當終端出現時，您可以輸入您的身份驗證程式碼、密碼或密碼短語。

如果您仍然遇到問題，您可能需要在 settings.json 中新增以下屬性並重試

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

如果您使用的是 macOS 和 Linux，並且希望減少輸入密碼或令牌的次數，您可以**本地機器**上啟用 ControlMaster 功能，以便 OpenSSH 透過單個連線執行多個 SSH 會話。

啟用 ControlMaster

1. 將類似以下的條目新增到您的 SSH 配置檔案

   Host *
       ControlMaster auto
       ControlPath  ~/.ssh/sockets/%r@%h-%p
       ControlPersist  600
   

2. 然後執行 mkdir -p ~/.ssh/sockets 來建立套接字資料夾。

設定 SSH Agent

如果您使用帶密碼短語的金鑰連線到 SSH 主機，您應該確保 SSH Agent **在本地**執行。VS Code 將自動將您的金鑰新增到 Agent，這樣您就不必每次開啟遠端 VS Code 視窗時都輸入密碼短語。

要驗證 Agent 是否正在執行並且可以從 VS Code 的環境中訪問，請在本地 VS Code 視窗的終端中執行 ssh-add -l。您應該會看到 Agent 中金鑰的列表（或一條訊息表示它沒有金鑰）。如果 Agent 未執行，請按照這些說明啟動它。啟動 Agent 後，請務必重啟 VS Code。

Windows

要在 Windows 上自動啟用 SSH Agent，請啟動**本地管理員 PowerShell** 並執行以下命令

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

現在，Agent 將在登入時自動啟動。

Linux

要將 SSH Agent 置於後臺執行，請執行

eval "$(ssh-agent -s)"

要將 SSH Agent 在登入時自動啟動，請將這些行新增到您的 ~/.bash_profile 檔案中

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

macOS

Agent 在 macOS 上預設應該是執行的。

使本地 SSH Agent 在遠端可用

您本地機器上的 SSH Agent 允許 Remote - SSH 擴充套件連線到您選擇的遠端系統，而無需反覆提示輸入密碼短語，但是像 Git 這樣在遠端執行的工具無法訪問您已解鎖的本地私鑰。

您可以透過在遠端開啟整合終端並執行 ssh-add -l 來看到這一點。該命令應該會列出已解鎖的金鑰，但會報告無法連線到身份驗證 Agent 的錯誤。設定 ForwardAgent yes 使本地 SSH Agent 在遠端環境中可用，從而解決此問題。

您可以透過編輯 .ssh/config 檔案（或 Remote.SSH.configFile 設定的任何內容 - 使用**Remote-SSH: Open SSH Configuration File...** 命令確保）並新增以下內容來實現此目的

Host *
    ForwardAgent yes

請注意，您可能希望更具限制性，只為特定的命名主機設定此選項。

修復 SSH 檔案許可權錯誤

SSH 對檔案許可權要求嚴格，如果設定不正確，您可能會看到類似“警告：未受保護的私鑰檔案！”的錯誤。有幾種方法可以更新檔案許可權來解決此問題，具體方法將在下面的部分中介紹。

本地 SSH 檔案和資料夾許可權

macOS / Linux

在您的本地機器上，請確保設定了以下許可權

Windows

具體期望的許可權可能因您使用的 SSH 實現而異。我們建議使用開箱即用的 Windows 10 OpenSSH 客戶端。

在這種情況下，請確保您在 SSH 主機的遠端使用者的所有 .ssh 資料夾中的檔案都由您擁有，並且沒有其他使用者可以訪問它們。有關詳細資訊，請參閱 Windows OpenSSH wiki。

對於所有其他客戶端，請查閱您的客戶端文件以瞭解其實現的要求。

伺服器 SSH 檔案和資料夾許可權

macOS / Linux

在您正在連線的遠端機器上，請確保設定了以下許可權

請注意，目前僅支援 Linux 主機，因此已省略 macOS 和 Windows 10 的許可權。

Windows

有關設定 Windows OpenSSH 伺服器的適當檔案許可權的詳細資訊，請參閱 Windows OpenSSH wiki。

安裝受支援的 SSH 客戶端

VS Code 將在 PATH 中查詢 ssh 命令。如果找不到，在 Windows 上，它會嘗試在 Git for Windows 的預設安裝路徑中查詢 ssh.exe。您也可以透過將 remote.SSH.path 屬性新增到 settings.json 來明確告訴 VS Code SSH 客戶端的位置。

安裝受支援的 SSH 伺服器

解決 Git 在 SSH 主機上推送或同步時掛起的問題

如果您使用 SSH 克隆 Git 儲存庫，並且您的 SSH 金鑰帶有密碼短語，則 VS Code 的拉取和同步功能在遠端執行時可能會掛起。

請使用不帶密碼短語的 SSH 金鑰，使用 HTTPS 克隆，或者從命令列執行 git push 來解決此問題。

使用 SSHFS 訪問遠端主機上的檔案

SSHFS 是一種安全的遠端檔案系統訪問協議，它建立在 SFTP 之上。與 CIFS / Samba 共享相比，它具有優勢，因為只需要 SSH 訪問該機器。

注意：出於效能原因，SSHFS 最適合用於單個檔案編輯以及上傳/下載內容。如果您需要使用一個應用程式對許多檔案進行批次讀/寫（例如本地原始碼管理工具），rsync 是更好的選擇。

macOS / Linux:

在 Linux 上，您可以使用發行版的包管理器安裝 SSHFS。對於 Debian/Ubuntu：sudo apt-get install sshfs

注意： WSL 1 不支援 FUSE 或 SSHFS，因此目前 Windows 上的說明有所不同。**WSL 2 確實包括 FUSE 和 SSHFS 支援**，所以這一點很快就會改變。

在 macOS 上，您可以使用 Homebrew 安裝 SSHFS

brew install --cask macfuse
brew install gromgit/fuse/sshfs-mac
brew link --overwrite sshfs-mac

此外，如果您不想使用命令列掛載遠端檔案系統，還可以安裝 SSHFS GUI。

要使用命令列，請在本地終端中執行以下命令（將 user@hostname 替換為遠端使用者和主機名 / IP）

export USER_AT_HOST=user@hostname
# Make the directory where the remote filesystem will be mounted
mkdir -p "$HOME/sshfs/$USER_AT_HOST"
# Mount the remote filesystem
sshfs "$USER_AT_HOST:" "$HOME/sshfs/$USER_AT_HOST" -ovolname="$USER_AT_HOST" -p 22  \
    -o workaround=nonodelay -o transform_symlinks -o idmap=user  -C

這將使您在遠端機器上的主資料夾在 ~/sshfs 下可用。完成後，您可以使用作業系統的 Finder / 檔案資源管理器或透過命令列解除安裝它

umount "$HOME/sshfs/$USER_AT_HOST"

Windows

請按照以下步驟操作：

1. 在 Linux 上，將 .gitattributes 檔案新增到您的專案中，以**強制 Linux 和 Windows 之間保持一致的換行符**，避免由於兩個作業系統之間的 CRLF/LF 差異而引起的意外問題。有關詳細資訊，請參閱解決 WSL 中 Git 換行符問題導致大量檔案修改。

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

3. 安裝 SSHFS for Windows 後，您可以使用檔案資源管理器的**對映網路驅動器...**選項，路徑為 \\sshfs\user@hostname，其中 user@hostname 是您的遠端使用者和主機名 / IP。您可以使用命令提示符透過以下方式指令碼化此操作：net use /PERSISTENT:NO X: \\sshfs\user@hostname

4. 完成後，在檔案資源管理器中右鍵單擊驅動器並選擇**斷開連線**以斷開連線。

從終端連線到遠端主機

配置好主機後，您可以直接從終端傳遞遠端 URI 來連線到它。

例如，要連線到 remote_server 並開啟 /code/my_project 資料夾，請執行

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

我們需要進行一些猜測，以確定輸入路徑是檔案還是資料夾。如果它具有副檔名，則被視為檔案。

要強制開啟一個資料夾，請在路徑末尾新增斜槓或使用

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

要強制開啟一個檔案，請新增 --goto 或使用

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

使用 rsync 維護原始碼的本地副本

除了使用 SSHFS 訪問遠端檔案之外，另一種方法是使用 rsync 將遠端主機上的資料夾的全部內容複製到您的本地機器。rsync 命令每次執行時都會確定需要更新哪些檔案，這比使用 scp 或 sftp 等工具更高效、更方便。這主要是在您確實需要使用多檔案或效能密集型的本地工具時需要考慮的。

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

或使用 PowerShell 在 Windows 中透過 WSL

wsl rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" "`$(wslpath -a '$PWD')"

您可以每次需要獲取檔案的最新副本時重新執行此命令，並且只會傳輸更新。.git 資料夾被故意排除，既是為了效能原因，也是為了讓您可以使用本地 Git 工具而不必擔心遠端主機上的狀態。

要推送內容，請反轉命令中的源和目標引數。但是，在 Windows 上，您應該在進行此操作之前向專案中新增一個 .gitattributes 檔案以強制一致的換行符。有關詳細資訊，請參閱解決 WSL 中導致許多檔案修改的 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 伺服器程序，並刪除伺服器安裝所在的資料夾。

如果您想手動執行這些步驟，或者該命令對您不起作用，您可以執行類似這樣的指令碼

# 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 文件，其中包含有關獲取日誌檔案和嘗試更多可能有助於縮小問題範圍的步驟的資訊。

Dev Containers 技巧

如果您想閱讀有關使用開發容器的提示，可以前往開發容器提示和技巧。

WSL 技巧

首次啟動：VS Code 伺服器先決條件

某些 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 月更新（版本 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 版本，code 命令只能使用預設發行版。因此，WSL 擴充套件可能會提示您是否同意更改預設發行版。

您始終可以使用 wslconfig.exe 來更改您的預設設定。

例如

wslconfig /setdefault Ubuntu

透過執行以下命令，您可以檢視已安裝的發行版

wslconfig /l

配置伺服器啟動的環境

當 WSL 擴充套件在 WSL 中啟動 VS Code 伺服器時，它不會執行任何 shell 配置檔案。這樣做是為了避免自定義配置檔案可能阻止啟動。

如果需要配置啟動環境，可以使用此處所述的環境設定指令碼。

配置遠端擴充套件主機環境

遠端擴充套件主機和終端的環境基於預設 shell 的配置檔案。要評估遠端擴充套件主機程序的環境變數，伺服器會建立一個預設 shell 的例項作為互動式登入 shell。它從中探測環境變數，並將其用作遠端擴充套件主機程序的初始環境。因此，環境變數的值取決於配置為預設值的 shell 以及該 shell 的配置檔案內容。

有關每個 shell 配置檔案的概述，請參閱Unix shell 初始化。大多數 WSL 發行版都將 /bin/bash 配置為預設 shell。/bin/bash 將首先查詢 /etc/profile 下的啟動檔案，然後查詢 ~/.bash_profile、~/.bash_login、~/.profile 下的任何啟動檔案。

要更改 WSL 發行版的預設 shell，請遵循這篇博文中的說明。

修復“code”命令不起作用的問題

如果從 Windows 上的 WSL 終端鍵入 code 命令不起作用，因為找不到 code，則您可能缺少 WSL 中 PATH 的一些關鍵位置。

透過開啟 WSL 終端並鍵入 echo $PATH 來檢查。您應該會看到 VS Code 的安裝路徑。預設情況下，這應該是

/mnt/c/Users/Your Username/AppData/Local/Programs/Microsoft VS Code/bin

但是，如果您使用了系統安裝程式，安裝路徑是

/mnt/c/Program Files/Microsoft VS Code/bin

...或者...

/mnt/c/Program Files (x86)/Microsoft VS Code/bin

這是 WSL 的一項功能，即路徑是從 Windows 中的 PATH 變數繼承的。要更改 Windows PATH 變數，請使用 Windows 開始選單中的編輯帳戶的環境變數命令。

如果您停用了路徑共享功能，請編輯您的 .bashrc，新增以下內容，然後啟動新終端

WINDOWS_USERNAME="Your Windows Alias"

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

注意：請確保用引號括起來或轉義目錄名稱中的空格字元。

查詢“code”命令的問題

如果從 Windows 命令提示符鍵入 code 不會啟動 VS Code，則可以透過執行 VSCODE_WSL_DEBUG_INFO=true code . 來幫助我們診斷問題。

請提交一個問題並附上完整的輸出。

查詢啟動或連線到伺服器的問題

當 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: permission denied 錯誤

這是 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 推送或同步掛起問題

如果您使用 SSH 克隆 Git 儲存庫，並且您的 SSH 金鑰帶有密碼短語，則 VS Code 的拉取和同步功能在遠端執行時可能會掛起。

請使用不帶密碼短語的 SSH 金鑰，使用 HTTPS 克隆，或者從命令列執行 git push 來解決此問題。

GitHub Codespaces 技巧

有關GitHub Codespaces的提示和問題，請參閱GitHub Codespaces 文件。您還可以檢視可能影響 Codespaces 的已知 Web 限制和適應性。

擴充套件技巧

雖然許多擴充套件可以正常工作，但仍有一些問題可能導致某些功能無法按預期工作。在某些情況下，您可以使用另一個命令來解決問題，而在其他情況下，則可能需要修改擴充套件。本節提供了常見問題的快速參考以及解決這些問題的提示。您還可以參考關於支援遠端開發的主要擴充套件文章，其中提供了有關修改擴充套件以支援遠端擴充套件主機的深入指南。

解決缺少依賴項的錯誤

某些擴充套件依賴於基本安裝的某些 WSL Linux 發行版中找不到的庫。您可以使用其包管理器將其他庫新增到您的 Linux 發行版中。對於 Ubuntu 和 Debian 系列發行版，執行 sudo apt-get install <package> 來安裝所需的庫。檢查您的擴充套件文件或錯誤訊息中提到的執行時以獲取其他安裝詳細資訊。

本地絕對路徑設定在遠端應用時失敗

VS Code 的本地使用者設定在連線到遠端終結點時會被重用。雖然這可以保持您的使用者體驗一致，但您可能需要在本地計算機和每個主機/容器/WSL 之間更改絕對路徑設定，因為目標位置不同。

解決方案：連線到遠端終結點後，可以透過從命令面板（F1）執行Preferences: Open Remote Settings命令，或透過在設定編輯器中選擇Remote選項卡來設定終結點特定的設定。這些設定將在您連線時覆蓋您現有的任何本地設定。

需要在遠端終結點上安裝本地 VSIX

有時您想在遠端計算機上安裝本地 VSIX，無論是開發過程中還是當擴充套件作者要求您試用修復補丁時。

解決方案：連線到 SSH 主機、容器或 WSL 後，您可以像在本地一樣安裝 VSIX。從命令面板（F1）執行Extensions: Install from VSIX...命令。您可能還想在 settings.json 中新增 "extensions.autoUpdate": false 以防止自動更新到最新的 Marketplace 版本。有關在遠端環境中開發和測試擴充套件的更多資訊，請參閱支援遠端開發。

本地瀏覽器未開啟

某些擴充套件使用外部 node 模組或自定義程式碼來啟動瀏覽器視窗。不幸的是，這可能導致擴充套件在遠端啟動瀏覽器，而不是在本地啟動。

解決方案：擴充套件可以使用 vscode.env.openExternal API 來解決此問題。有關詳細資訊，請參閱擴充套件作者指南。

剪貼簿不起作用

某些擴充套件使用 clipboardy 等 node 模組與剪貼簿整合。不幸的是，這可能導致擴充套件在遠端端錯誤地與剪貼簿整合。

解決方案：擴充套件可以切換到 VS Code 剪貼簿 API 來解決此問題。有關詳細資訊，請參閱擴充套件作者指南。

無法從瀏覽器或應用程式訪問本地 Web 伺服器

在容器、SSH 主機中工作或透過 GitHub Codespaces 工作時，瀏覽器連線到的埠可能會被阻止。

解決方案：擴充套件可以使用 vscode.env.openExternal 或 vscode.env.asExternalUri API（自動轉發 localhost 埠）來解決此問題。有關詳細資訊，請參閱擴充套件作者指南。作為一種變通方法，請使用Forward a Port命令手動進行。

Webview 內容不顯示

如果擴充套件的 webview 內容使用 iframe 連線到本地 Web 伺服器，則 webview 連線到的埠可能會被阻止。此外，如果擴充套件硬編碼 vscode-resource:// URI 而不是使用 asWebviewUri，則內容可能不會顯示在 Codespaces 瀏覽器編輯器中。

解決方案：擴充套件可以使用 webview.asWebviewUri 來解決 vscode-resource:// URI 的問題。

如果埠被阻止，最佳方法是使用webview 訊息傳遞 API。作為一種變通方法，可以使用 vscode.env.asExternalUri 允許 webview 連線到從 VS Code 啟動的 localhost Web 伺服器。但是，目前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 伺服器掛起或崩潰的情況。如果擴充套件立即啟用，這可能會阻止您連線並解除安裝該擴充套件。

解決方案：按照以下步驟手動刪除遠端擴充套件資料夾

1. 對於容器，請確保您的 devcontainer.json 不再包含對有問題的擴充套件的引用。

2. 接下來，使用單獨的終端/命令提示符連線到遠端主機、容器或 WSL。

   • 如果使用 SSH 或 WSL，請相應地連線到環境（執行 ssh 連線到伺服器或開啟 WSL 終端）。
   • 如果使用容器，請透過呼叫 docker ps -a 並檢視名稱正確的映像列表來識別容器 ID。如果容器已停止，請執行 docker run -it <id> /bin/sh。如果正在執行，請執行 docker exec -it <id> /bin/sh。

3. 連線後，執行 rm -rf ~/.vscode-server/extensions 以用於 VS Code stable，以及/或 rm -rf ~/.vscode-server-insiders/extensions 以用於 VS Code Insiders，以刪除所有擴充套件。

包含或獲取預編譯本機模組的擴充套件失敗

VS Code 擴充套件捆綁（或動態獲取）的本機模組必須使用 Electron 的 electron-rebuild 進行重新編譯。但是，VS Code 伺服器執行的是標準（非 Electron）版本的 Node.js，這可能導致二進位制檔案在遠端使用時失敗。

解決方案：需要修改擴充套件以解決此問題。它們需要包含（或動態獲取）Electron 和標準 Node.js 的二進位制檔案集，以用於 VS Code 提供的 Node.js 的“modules”版本，然後在啟用函式中檢查 context.executionContext === vscode.ExtensionExecutionContext.Remote 以設定正確的二進位制檔案。有關詳細資訊，請參閱擴充套件作者指南。

擴充套件僅在非 x86_64 主機或 Alpine Linux 上失敗

如果一個擴充套件在 Debian 9+、Ubuntu 16.04+ 或 RHEL/CentOS 7+ 遠端 SSH 主機、容器或 WSL 上工作，但在支援的非 x86_64 主機（例如 ARMv7l）或 Alpine Linux 容器上失敗，則該擴充套件可能只包含不支援這些平臺的本機程式碼或執行時。例如，擴充套件可能只包含 x86_64 編譯的本機模組或執行時版本。對於 Alpine Linux，由於 Alpine Linux (musl) 和其他發行版 (glibc) 中 libc 的實現方式存在根本性差異，包含的本機程式碼或執行時可能無法工作。

解決方案：擴充套件需要透過為這些附加目標編譯/包含二進位制檔案來選擇支援這些平臺。需要注意的是，一些第三方 npm 模組也可能包含可能導致此問題的本機程式碼。因此，在某些情況下，您可能需要與 npm 模組作者合作以新增附加的編譯目標。有關詳細資訊，請參閱擴充套件作者指南。

擴充套件因缺少模組而失敗

依賴於 Electron 或 VS Code 基本模組（未透過擴充套件 API 公開）且未提供備用方案的擴充套件在遠端執行時可能會失敗。您可能會在開發者工具控制檯中看到類似 original-fs 未找到的錯誤。

解決方案：刪除對 Electron 模組的依賴或提供備用方案。有關詳細資訊，請參閱擴充套件作者指南。

無法訪問/將遠端工作區檔案傳輸到本地計算機

將工作區檔案開啟到外部應用程式的擴充套件可能會遇到錯誤，因為外部應用程式無法直接訪問遠端檔案。

解決方案：如果您建立了一個旨在本地執行的“UI”擴充套件，則可以使用 vscode.workspace.fs API 與遠端工作區檔案系統進行互動。然後，您可以將其作為“Workspace”擴充套件的依賴項，並在需要時透過命令呼叫它。有關不同型別的擴充套件以及如何使用命令在它們之間進行通訊的詳細資訊，請參閱擴充套件作者指南。

無法從擴充套件訪問已連線的裝置

訪問本地連線裝置的擴充套件在遠端執行時將無法連線到它們。

解決方案：目前尚無。我們正在研究解決此問題的最佳方法。

問題和反饋

報告問題

如果您遇到遠端開發擴充套件問題，收集正確的日誌至關重要，以便我們能夠幫助診斷您的問題。

每個遠端擴充套件都有一個用於檢視其日誌的命令。

您可以透過命令面板（F1）中的Remote-SSH: Show Log來獲取 Remote - SSH 擴充套件日誌。在報告 Remote - SSH 問題時，請同時驗證您是否可以從外部終端（不使用 Remote - SSH）SSH 連線到您的計算機。

同樣，您可以透過Dev Containers: Show Container Log獲取 Dev Containers 擴充套件日誌。

與上面兩個類似，您可以透過WSL: Show Log獲取 WSL 擴充套件日誌。另外，請檢查您的問題是否已在WSL 儲存庫中進行跟蹤（並且不是由於 WSL 擴充套件引起）。

如果您在使用其他擴充套件進行遠端開發時遇到問題（例如，其他擴充套件在遠端上下文中未正確載入或安裝），則從Remote Extension Host輸出通道（Output: Focus on Output View）獲取日誌，並從下拉列表中選擇Log (Remote Extension Host) 會很有幫助。

注意：如果您只看到Log (Extension Host)，則這是本地擴充套件主機，遠端擴充套件主機未啟動。這是因為日誌通道僅在建立日誌檔案後建立，因此如果遠端擴充套件主機未啟動，則未建立遠端擴充套件主機日誌檔案，並且未在輸出檢視中顯示。在您的問題中包含此資訊仍然很有幫助。

遠端問題和反饋資源

我們有各種其他遠端資源

• 請參閱遠端開發 FAQ。
• 在 Stack Overflow 上搜索。
• 新增功能請求或報告問題。