遠端開發技巧和竅門

本文介紹了 Visual Studio Code 遠端開發 擴充套件的故障排除技巧和竅門。有關設定和使用各個擴充套件的詳細資訊，請參閱 SSH、容器 和 WSL 文章。或者嘗試入門級的 教程，幫助您在遠端環境中快速執行起來。

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

SSH 技巧

SSH 功能強大且靈活，但這也會增加一些設定複雜性。本節包含一些在不同環境中啟動和執行遠端 - SSH 擴充套件的技巧和竅門。

自定義 AI 聊天響應

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

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

配置 $EDITOR 變數

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

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

對於 Windows 主機，以下是等效的 PowerShell

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

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

配置基於金鑰的身份驗證

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

提示： Windows 上的 PuTTY 不是 受支援的客戶端，但您可以轉換您的 PuTTYGen 金鑰。

快速入門：使用 SSH 金鑰

要為您的遠端主機設定基於 SSH 金鑰的身份驗證。首先，我們將建立一個金鑰對，然後將公鑰複製到主機。

建立您的本地 SSH 金鑰對

檢查您的本地計算機上是否已存在 SSH 金鑰。在 macOS / Linux 上，這通常位於 ~/.ssh/id_ed25519.pub；在 Windows 上，位於使用者配置檔案資料夾中的 .ssh 目錄（例如 C:\Users\your-user\.ssh\id_ed25519.pub）。

如果您沒有金鑰，請在本地終端 / PowerShell 中執行以下命令來生成 SSH 金鑰對

ssh-keygen -t ed25519 -b 4096

提示： 沒有 ssh-keygen？安裝 受支援的 SSH 客戶端。

限制私鑰檔案的許可權

• 對於 macOS / Linux，執行以下 shell 命令，如果需要，請替換為您的私鑰路徑

  chmod 400 ~/.ssh/id_ed25519
  

• 對於 Windows，在 PowerShell 中執行以下命令，為您的使用者名稱授予明確的讀取許可權

  icacls "privateKeyPath" /grant <username>:R
  

  然後導航到 Windows 資源管理器中的私鑰檔案，右鍵單擊並選擇屬性。選擇安全選項卡 > 高階 > 停用繼承 > 從該物件中刪除所有繼承的許可權。

授權您的 macOS 或 Linux 機器連線

在本地終端視窗中執行以下命令之一，根據需要替換使用者和主機名，將您的本地公鑰複製到 SSH 主機。

• 連線到 macOS 或 Linux SSH 主機

  export USER_AT_HOST="your-user-name-on-host@hostname"
  export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
  
  ssh-copy-id -i "$PUBKEYPATH" "$USER_AT_HOST"
  

• 連線到 Windows SSH 主機

  • 主機使用 OpenSSH 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. 從應用程式選單中選擇轉換 > 匯出 OpenSSH 金鑰。將轉換後的金鑰儲存到使用者配置檔案資料夾中的.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
   

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

遠端 - 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，將遠端 - 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 伺服器上可能已停用此功能。要檢視這是否是問題所在，請在輸出視窗中開啟 Remote - SSH 類別並檢查以下訊息

open failed: administratively prohibited: open failed

如果您確實看到該訊息，請按照以下步驟更新 SSH 伺服器的 sshd 配置

1. 在 SSH 主機（而不是本地）上的文字編輯器（如 Vim、nano、Pico 或記事本）中開啟 /etc/ssh/sshd_config 或 C:\ProgramData\ssh\sshd_config。
2. 新增設定 AllowTcpForwarding yes。
3. 重新啟動 SSH 伺服器。（在 Ubuntu 上，執行 sudo systemctl restart sshd。在 Windows 上，在管理員 PowerShell 中執行 Restart-Service sshd。）
4. 重試。

在 SSH 配置檔案中設定 ProxyCommand 引數

如果您在代理後面並且無法連線到 SSH 主機，您可能需要為您的主機在本地 SSH 配置檔案中使用 ProxyCommand 引數。您可以閱讀這篇 SSH ProxyCommand 文章以獲取其用法的示例。

確保遠端機器有網際網路訪問

遠端機器必須有網際網路訪問才能從 Marketplace 下載 VS Code Server 和擴充套件。有關連線要求的詳細資訊，請參閱常見問題。

在遠端主機上設定 HTTP_PROXY / HTTPS_PROXY

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

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

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

解決 /tmp 以 noexec 方式掛載的問題

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

檢查安裝期間是否啟動了不同的 shell

一些使用者從他們的 .bash_profile 或其他啟動指令碼在他們的 SSH 主機上啟動不同的 shell，因為他們想使用與預設不同的 shell。這可能會破壞 VS Code 的遠端伺服器安裝指令碼，不建議這樣做。相反，使用 chsh 在遠端機器上更改您的預設 shell。

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

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

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

聯絡您的系統管理員尋求配置幫助

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

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

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

啟用備用 SSH 身份驗證方法

如果您正在連線到 SSH 遠端主機，並且是

• 使用雙因素身份驗證連線
• 使用密碼身份驗證
• 當 SSH 代理未執行或不可訪問時，使用帶有密碼的 SSH 金鑰

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

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

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

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

要啟用 ControlMaster

1. 將如下條目新增到您的 SSH 配置檔案中

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

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

設定 SSH 代理

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

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

Windows

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

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

現在，代理將在登入時自動啟動。

Linux

要在後臺啟動 SSH Agent，請執行

eval "$(ssh-agent -s)"

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

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

macOS

代理預設應該在 macOS 上執行。

使本地 SSH Agent 在遠端可用

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

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

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

Host *
    ForwardAgent yes

請注意，您可能希望更嚴格，僅為特定的命名主機設定此選項。

修復 SSH 檔案許可權錯誤

SSH 對檔案許可權有嚴格要求，如果設定不正確，您可能會看到“WARNING: UNPROTECTED PRIVATE KEY FILE!”之類的錯誤。有幾種方法可以更新檔案許可權以解決此問題，如下面的部分所述。

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

macOS / Linux

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

Windows

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

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

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

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

macOS / Linux

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

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

Windows

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

安裝受支援的 SSH 客戶端

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

安裝受支援的 SSH 伺服器

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

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

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

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

SSHFS 是一種安全的遠端檔案系統訪問協議，它基於 SFTP 構建。它比 CIFS / Samba 共享等具有優勢，因為它只需要對機器進行 SSH 訪問。

注意： 出於效能原因，SSHFS 最適合用於單檔案編輯和內容上傳/下載。如果您需要使用一次性批次讀寫大量檔案的應用程式（例如本地原始碼控制工具），則 rsync 是更好的選擇。

macOS / Linux:

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

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

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

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

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

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

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

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

umount "$HOME/sshfs/$USER_AT_HOST"

Windows

請按照以下步驟操作：

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

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

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

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

從終端連線到遠端主機

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

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

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

我們需要猜測輸入路徑是檔案還是資料夾。如果它有副檔名，則被視為檔案。

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

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

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

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

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

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

rsync 命令在 macOS 上開箱即用，可以使用 Linux 包管理器安裝（例如 Debian/Ubuntu 上的 sudo apt-get install rsync）。對於 Windows，您需要使用 WSL 或 Cygwin 才能訪問該命令。

要使用該命令，請導航到要儲存同步內容的資料夾，然後執行以下命令，將 user@hostname 替換為遠端使用者和主機名/IP，將 /remote/source/code/path 替換為遠端原始碼位置。

在 macOS、Linux 或 WSL 內部

rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" .

或者使用 Windows 上的 PowerShell 中的 WSL

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

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

要推送內容，請反轉命令中的源和目標引數。但是，在 Windows 上，您應該在專案新增一個 .gitattributes 檔案，以在執行此操作之前強制保持一致的行尾符。有關詳細資訊，請參閱 解決 Git 行尾符問題。

rsync -rlptzv --progress --delete --exclude=.git . "user@hostname:/remote/source/code/path"

清理遠端上的 VS Code Server

SSH 擴充套件提供了一個用於從遠端機器清理 VS Code Server 的命令：Remote-SSH: Uninstall VS Code Server from Host...。該命令執行兩項操作：它會殺死所有正在執行的 VS Code Server 程序，並刪除安裝伺服器的資料夾。

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

# Kill server processes
kill -9 $(ps aux | grep vscode-server | grep $USER | grep -v grep | awk '{print $2}')
# Delete related files and folder
rm -rf $HOME/.vscode-server # Or ~/.vscode-server-insiders

VS Code Server 之前安裝在 ~/.vscode-remote 下，因此您也可以檢查該位置。

SSH 進入遠端 WSL 2 主機

您可能希望使用 SSH 連線到在遠端機器上執行的 WSL 發行版。請檢視本指南，瞭解如何從外部機器透過 SSH 連線到 Windows 10 上的 Bash 和 WSL 2。

提交問題

如果您在使用 Remote-SSH 擴充套件時遇到問題並認為需要提交問題，請首先確保您已閱讀本網站上的文件，然後參閱 故障排除 wiki 文件，瞭解如何獲取日誌檔案並嘗試更多可能有助於縮小問題來源的步驟。

開發容器技巧

如果您想了解有關使用開發容器的技巧，可以訪問開發容器 技巧和竅門。

WSL 技巧

首次啟動：VS Code Server 的先決條件

某些 WSL Linux 發行版缺少 VS Code server 啟動所需的庫。您可以使用其包管理器將額外的庫新增到您的 Linux 發行版中。

Debian 和 Ubuntu

開啟 Debian 或 Ubuntu WSL shell 以新增 wget 和 ca-certificates

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

Alpine

以 root 使用者身份開啟 Alpine WSL shell (wsl -d Alpine -u root) 以新增 libstdc++

apk update && apk add libstdc++

在 Windows 10 2018 年 4 月更新 (Build 1803) 及更早版本中，需要 /bin/bash

apk update && apk add bash

選擇 WSL 擴充套件使用的發行版

WSL: New Window 將開啟註冊為預設的 WSL 發行版。

要開啟非預設發行版，請從要使用的發行版的 WSL shell 中執行 code .，或使用 WSL: New Window using Distro。

在早於 Windows 10 2019 年 5 月更新 (版本 1903) 的 WSL 版本中，WSL 命令只能使用預設發行版。因此，WSL 擴充套件可能會提示您是否同意更改預設發行版。

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

例如

wslconfig /setdefault Ubuntu

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

wslconfig /l

配置伺服器啟動的環境

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

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

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

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

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

要更改 WSL 發行版的預設 shell，請按照此部落格文章的說明進行操作。

修復程式碼命令無法工作的問題

如果在 Windows 上的 WSL 終端中鍵入 code 無效，因為找不到 code，則您的 WSL PATH 中可能缺少一些關鍵位置。

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

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

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

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

...或者...

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

WSL 的一個特性是路徑是從 Windows 中的 PATH 變數繼承的。要更改 Windows PATH 變數，請使用 Windows 開始選單中的編輯您的帳戶的環境變數命令。

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

WINDOWS_USERNAME="Your Windows Alias"

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

注意： 務必在目錄名稱中使用引號或轉義空格字元。

查詢“code”命令的問題

如果在 Windows 命令提示符下鍵入 code 未能啟動 VS Code，您可以透過執行 VSCODE_WSL_DEBUG_INFO=true code . 幫助我們診斷問題。

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

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

當 WSL 視窗無法連線到遠端伺服器時，您可以在 WSL 日誌中獲取更多資訊。提交問題時，務必始終傳送 WSL 日誌的完整內容。

透過執行命令 WSL: Open Log 開啟 WSL 日誌。日誌將顯示在終端檢視的 WSL 選項卡下。

要獲取更詳細的日誌記錄，請在使用者設定中啟用 remote.WSL.debug 設定。

伺服器因段錯誤而啟動失敗

您可以透過向我們傳送核心轉儲檔案來幫助我們調查此問題。要獲取核心轉儲檔案，請按照以下步驟操作

在 Windows 命令提示符中

• 執行 code --locate-extension ms-vscode-remote.remote-wsl 以確定 WSL 擴充套件資料夾。
• cd 到返回的路徑。
• 使用 VS Code 開啟 wslServer.sh 指令碼，code .\scripts\wslServer.sh。
• 在最後一行之前（在 "$VSCODE_REMOTE_BIN/$COMMIT/bin/$SERVER_APPNAME" "$@" 之前），新增 ulimit -C unlimited。
• 啟動執行遠端伺服器的 WSL 視窗，並等待段錯誤。

核心檔案將位於上面提到的 WSL 擴充套件資料夾中。

我看到 EACCES: 許可權被拒絕錯誤，嘗試重新命名開啟的工作區中的資料夾

這是 WSL 檔案系統實現的一個已知問題（Microsoft/WSL#3395，Microsoft/WSL#1956），由 VS Code 啟用的檔案監視器引起。該問題僅在 WSL 2 中修復。

為了避免此問題，請將 remote.WSL.fileWatcher.polling 設定為 true。但是，基於輪詢對於大型工作區會產生效能影響。

對於大型工作區，您可能需要增加輪詢間隔 remote.WSL.fileWatcher.pollingInterval，並透過 files.watcherExclude 控制要監視的資料夾。

WSL 2 沒有檔案監視器問題，並且不受新設定的影響。

解決 WSL 中的 Git 行尾問題（導致許多檔案被修改）

由於 Windows 和 Linux 使用不同的預設行尾符，Git 可能會報告大量除了行尾符之外沒有其他差異的已修改檔案。為了防止這種情況發生，您可以使用 .gitattributes 檔案或在 Windows 端全域性停用行尾符轉換。

通常，在倉庫中新增或修改 .gitattributes 檔案是解決此問題最可靠的方法。將此檔案提交到原始碼控制將有助於其他人，並允許您根據需要針對每個倉庫調整行為。例如，將以下內容新增到倉庫根目錄下的 .gitattributes 檔案將強制所有內容都為 LF，除了需要 CRLF 的 Windows 批處理檔案

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

請注意，這適用於 Git v2.10+，因此如果您遇到問題，請確保已安裝最新的 Git 客戶端。您可以將倉庫中需要 CRLF 的其他檔案型別新增到此同一檔案中。

如果您仍然希望始終上傳 Unix 風格的行尾符 (LF)，您可以使用 input 選項。

git config --global core.autocrlf input

如果您希望完全停用行尾符轉換，請改為執行以下命令

git config --global core.autocrlf false

最後，您可能需要再次克隆倉庫才能使這些設定生效。

在 Windows 和 WSL 之間共享 Git 憑據

如果您使用 HTTPS 克隆您的倉庫，並且在 Windows 中配置了 憑據助手，您可以與 WSL 共享此憑據助手，以便您輸入的密碼在兩端都持久儲存。（請注意，這不適用於使用 SSH 金鑰。）

只需按照以下步驟操作

1. 在 Windows 命令提示符或 PowerShell 中執行以下命令，配置 Windows 上的憑據管理器

    git config --global credential.helper wincred
   

2. 在 WSL 終端中執行以下命令，配置 WSL 使用相同的憑據助手

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

現在，您在 Windows 端使用 Git 時輸入的任何密碼都將可供 WSL 使用，反之亦然。

解決從 WSL 執行 Git 推送或同步時掛起的問題

如果您使用 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 命令或在設定編輯器中選擇遠端選項卡來設定特定於端點的設定。這些設定將在您連線時覆蓋您現有的任何本地設定。

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

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

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

瀏覽器無法在本地開啟

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

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

剪貼簿無法工作

一些擴充套件使用像 clipboardy 這樣的 Node 模組來與剪貼簿整合。不幸的是，這可能會導致擴充套件在遠端端錯誤地與剪貼簿整合。

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

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

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

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

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 伺服器。但是，目前 Codespaces 基於瀏覽器的編輯器（僅限）被 MicrosoftDocs/vscodespaces#11 阻止。有關解決方法詳細資訊，請參閱擴充套件作者指南。

阻塞的 localhost 埠

如果您嘗試從外部應用程式連線到 localhost 埠，該埠可能會被阻止。

解決方案： VS Code 1.40 引入了一個新的 vscode.env.asExternalUri API，供擴充套件以程式設計方式轉發任意埠。有關詳細資訊，請參閱擴充套件作者指南。作為一種解決方法，您可以使用轉發埠命令手動執行此操作。

儲存擴充套件資料時出錯

擴充套件可能會嘗試透過查詢 Linux 上的 ~/.config/Code 資料夾來持久化全域性資料。該資料夾可能不存在，這可能會導致擴充套件丟擲諸如 ENOENT: no such file or directory, open '/root/.config/Code/User/filename-goes-here 之類的錯誤。

解決方案： 擴充套件可以使用 context.globalStorageUri 或 context.storageUri 屬性來解決此問題。有關詳細資訊，請參閱擴充套件作者指南。

無法登入 / 每次連線新端點時都必須登入

需要登入的擴充套件可能會使用自己的程式碼來持久化金鑰。此程式碼可能因缺少依賴項而失敗。即使成功，金鑰也將遠端儲存，這意味著您必須為每個新端點登入。

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

不相容的擴充套件阻止 VS Code 連線

如果遠端主機、容器或 WSL 中安裝了不相容的擴充套件，我們已經看到由於不相容性導致 VS Code Server 掛起或崩潰的情況。如果擴充套件立即啟用，這可能會阻止您連線並解除安裝擴充套件。

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

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

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

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

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

釋出或獲取預構建原生模組的擴充套件失敗

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

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

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

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

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

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

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

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

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

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

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

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

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

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

問題和反饋

報告問題

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

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

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

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

與上面兩個類似，您可以透過 WSL: Show Log 獲取 WSL 擴充套件日誌。還要檢查您的問題是否在 WSL 倉庫中被跟蹤（並且不是由於 WSL 擴充套件引起的）。

如果您在使用其他擴充套件遠端時遇到問題（例如，其他擴充套件在遠端上下文中無法正常載入或安裝），則從遠端擴充套件主機輸出通道（輸出：聚焦輸出檢視）獲取日誌並從下拉列表中選擇日誌（遠端擴充套件主機）會很有幫助。

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

遠端問題和反饋資源

我們有各種其他遠端資源

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