遠端開發提示與技巧

本文涵蓋 Visual Studio Code 遠端開發擴充功能的疑難排解提示與技巧。如需設定及使用各特定擴充功能的詳細資訊，請參閱 SSH、容器和 WSL 文章。或嘗試入門的教學課程，以協助您快速在遠端環境中執行。

如需關於 GitHub Codespaces 的提示與問題，請參閱 GitHub Codespaces 文件。

SSH 提示

SSH 功能強大且彈性，但也增加了一些設定複雜性。本節包含一些提示與技巧，協助 Remote - SSH 擴充功能在不同環境中啟動並執行。

設定 $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: 開啟組態檔...，選取 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: 開啟組態檔...，選取您要變更的 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 取得。

依預設，伺服器會接聽本機電腦上隨機 TCP 連接埠上的 localhost，然後轉送到您的本機電腦。如果您連線至 Linux 或 macOS 主機，您可以切換為使用鎖定至特定使用者的 Unix Socket。然後轉送此 Socket 而非連接埠。

注意：此設定會停用連線多工，因此建議設定公開金鑰驗證。

若要設定它

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 切換為 Socket 模式。

   

3. 如果您已連線至 SSH 主機，請從命令面板 (F1) 選取 Remote-SSH: 終止主機上的 VS Code Server...，讓設定生效。

如果您在連線時遇到錯誤，您可能需要在 SSH 主機的 sshd 組態上啟用 Socket 轉送。若要執行此操作

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: 終止主機上的 VS Code Server。這會移除伺服器，這可以修正您可能看到的一系列問題和錯誤訊息，例如「無法建立與 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 伺服器的錯誤

由於 Windows 適用的某些版本的 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 轉送

Remote - 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 參數

如果您位於 Proxy 後方，且無法連線至您的 SSH 主機，您可能需要在本機 SSH 組態檔中針對您的主機使用 ProxyCommand 參數。您可以閱讀此 SSH ProxyCommand 文章，以取得其用法的範例。

確定遠端電腦具有網際網路存取權

遠端電腦必須具有網際網路存取權，才能從市集下載 VS Code Server 和擴充功能。如需連線需求的詳細資訊，請參閱 常見問題。

在遠端主機上設定 HTTP_PROXY / HTTPS_PROXY

如果您的遠端主機位於 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

某些使用者從其 SSH 主機上的 .bash_profile 或其他啟動指令碼啟動不同的 Shell，因為他們想要使用與預設 Shell 不同的 Shell。這可能會中斷 VS Code 的遠端伺服器安裝指令碼，且不建議使用。相反地，請使用 chsh 來變更遠端電腦上的預設 Shell。

連線至每次連線動態指派電腦的系統

某些系統會在每次建立 SSH 連線時，將 SSH 連線動態路由至叢集中的一個節點。這對 VS Code 來說是一個問題，因為它建立兩個連線以開啟遠端視窗：第一個連線用於安裝或啟動 VS Code Server (或尋找已在執行的執行個體)，第二個連線用於建立 SSH 連接埠通道，VS Code 使用該通道與伺服器通訊。如果 VS Code 在建立第二個連線時路由至不同的電腦，則它將無法與 VS Code Server 通訊。

此問題的一個解決方法是在 OpenSSH (僅限 macOS/Linux 用戶端) 中使用 ControlMaster 選項，如啟用替代 SSH 驗證方法中所述，以便 VS Code 的兩個連線將透過與相同節點的單一 SSH 連線進行多工處理。

聯絡您的系統管理員以取得組態說明

SSH 是一個非常彈性的通訊協定，並支援許多組態。如果您在登入終端機或 Remote-SSH 輸出視窗中看到其他錯誤，則可能是因為缺少設定。

聯絡您的系統管理員，以取得有關您的 SSH 主機和用戶端所需設定的資訊。連線至您的 SSH 主機的特定命令列引數可以新增至 SSH 組態檔。

若要存取您的組態檔，請在命令面板 (F1) 中執行 Remote-SSH: 開啟組態檔...。然後您可以與您的管理員合作，以新增必要的設定。

啟用替代 SSH 驗證方法

如果您要連線至 SSH 遠端主機，且符合下列其中一項

• 使用雙因素驗證連線
• 使用密碼驗證
• 當 SSH Agent 未執行或無法存取時，使用具有密碼的 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 以建立 Socket 資料夾。

設定 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: 開啟 SSH 組態檔... 命令以確定) 並新增

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 用戶端

執行 sudo yum install openssh-clients

VS Code 將在 PATH 中尋找 ssh 命令。如果失敗，在 Windows 上，它會嘗試在適用於 Windows 的預設 Git 安裝路徑中尋找 ssh.exe。您也可以透過將 remote.SSH.path 屬性新增至 settings.json，明確告知 VS Code 在哪裡找到 SSH 用戶端。

macOS 10.14+ (Mojave)

啟用遠端登入。

解決在 SSH 主機上執行 Git 推送或同步處理時擱置的問題

如果您使用 SSH 複製 Git 存放庫，且您的 SSH 金鑰具有密碼，則當遠端執行時，VS Code 的提取和同步處理功能可能會擱置。

請使用沒有密碼的 SSH 金鑰、使用 HTTPS 複製，或從命令列執行 git push 以解決此問題。

使用 SSHFS 存取遠端主機上的檔案

macOS / Linux:

SSHFS 是一種安全的遠端檔案系統存取通訊協定，建構於 SFTP 之上。與 CIFS/Samba 共用之類的通訊協定相比，它具有優勢，因為它只需要 SSH 存取電腦。

注意：基於效能考量，SSHFS 最適合用於單一檔案編輯和上傳/下載內容。如果您需要使用一次大量讀取/寫入多個檔案的應用程式 (例如本機原始碼控制工具)，rsync 是更好的選擇。

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

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

注意：WSL 1 不支援 FUSE 或 SSHFS，因此 Windows 目前的指示有所不同。WSL 2 包含 FUSE 和 SSHFS 支援，因此這種情況很快就會改變。

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

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 GUI。

umount "$HOME/sshfs/$USER_AT_HOST"

Windows

若要使用命令列，請從本機終端機執行下列命令 (將 user@hostname 更換為遠端使用者和主機名稱/ IP)

1. 這會讓您遠端電腦上的主資料夾在 ~/sshfs 下可用。完成後，您可以使用作業系統的 Finder/檔案總管或使用命令列來解除掛接

2. 遵循下列步驟

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

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

安裝適用於 Windows 的 SSHFS 後，您可以使用檔案總管的連線網路磁碟機... 選項，路徑為 \\sshfs\user@hostname，其中 user@hostname 是您的遠端使用者和主機名稱/ IP。您可以使用命令提示字元編寫指令碼，如下所示：net use /PERSISTENT:NO X: \\sshfs\user@hostname

完成後，在檔案總管中以滑鼠右鍵按一下磁碟機，然後選取中斷連線以中斷連線。

從終端機連線至遠端主機

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

設定主機後，您可以透過傳遞遠端 URI 從終端機直接連線至它。

例如，若要連線至 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 來存取命令。

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

若要使用命令，請導覽至您要儲存同步處理內容的資料夾，並執行下列命令，將 user@hostname 更換為遠端使用者和主機名稱/ IP，並將 /remote/source/code/path 更換為遠端原始碼位置。

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

在 macOS、Linux 或 WSL 內

或從 Windows 上的 PowerShell 使用 WSL

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

您可以每次想要取得檔案的最新複本時重新執行此命令，並且只會傳輸更新。.git 資料夾會刻意排除，這既是為了效能考量，也是為了讓您可以使用本機 Git 工具，而無需擔心遠端主機上的狀態。

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

清除遠端上的 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 擴充功能時遇到問題，並認為需要提交問題，請先確定您已詳閱本網站上的文件，然後查看疑難排解 Wiki 文件，以取得有關擷取記錄檔以及嘗試可能有助於縮小問題來源範圍的更多步驟的資訊。

開發容器提示

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

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 發行版。

若要開啟非預設的發行版，請從要使用的發行版的 WSL Shell 執行 code .，或使用 WSL: New Window using Distro (WSL：使用發行版新增視窗)。

對於 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 的設定指令碼內容。

請參閱Unix Shell 初始化，以概觀每個 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 開始功能表中的 Edit environment variables for your account (編輯您帳戶的環境變數) 命令。

如果您已停用路徑共用功能，請編輯您的 .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 記錄。記錄將顯示在 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 (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 推送或同步處理時擱置的問題

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... (擴充功能：從 VSIX 安裝...) 命令。您可能也想要將 "extensions.autoUpdate": false 新增至 settings.json，以防止自動更新至最新的 Marketplace 版本。請參閱支援遠端開發，以取得有關在遠端環境中開發和測試擴充功能的詳細資訊。

瀏覽器未在本機開啟

某些擴充功能使用外部節點模組或自訂程式碼來啟動瀏覽器視窗。遺憾的是，這可能會導致擴充功能在遠端而非本機啟動瀏覽器。

解決方案： 擴充功能可以使用 vscode.env.openExternal API 來解決此問題。請參閱擴充功能作者指南以取得詳細資訊。

剪貼簿無法運作

某些擴充功能使用節點模組 (例如 clipboardy) 與剪貼簿整合。遺憾的是，這可能會導致擴充功能錯誤地與遠端端的剪貼簿整合。

解決方案： 擴充功能可以切換至 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 伺服器。但是，這目前僅針對 Codespaces 以瀏覽器為基礎的編輯器 (僅限) 由 MicrosoftDocs/vscodespaces#11 封鎖。請參閱擴充功能作者指南以取得有關因應措施的詳細資訊。

封鎖的 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. 連線後，針對 VS Code Stable 執行 rm -rf ~/.vscode-server/extensions，和/或針對 VS Code Insiders 執行 rm -rf ~/.vscode-server-insiders/extensions，以移除所有擴充功能。

隨附或取得預先建置的原生模組的擴充功能失敗

與 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 問題時，也請確認您是否可以從外部終端機 (未使用 Remote-SSH) SSH 連線到您的電腦。

同樣地，您可以使用 Dev Containers: Show Container Log (開發容器：顯示容器記錄) 取得開發容器擴充功能記錄。

與上述兩者類似，您可以使用 WSL: Show Log (WSL：顯示記錄) 取得 WSL 擴充功能記錄。另請檢查您的問題是否正在 WSL 存放庫 中追蹤 (且並非 WSL 擴充功能造成)。

如果您在使用其他遠端擴充功能時遇到問題 (例如，其他擴充功能未在遠端內容中正確載入或安裝)，則從 Remote Extension Host (遠端擴充功能主機) 輸出通道 (Output: Focus on Output View (輸出：焦點放在輸出檢視)) 擷取記錄會很有幫助，並從下拉式清單中選取 Log (Remote Extension Host) (記錄 (遠端擴充功能主機))。

注意：如果您只看到 Log (Extension Host) (記錄 (擴充功能主機))，這是本機擴充功能主機，而遠端擴充功能主機未啟動。這是因為記錄通道僅在記錄檔建立後才會建立，因此如果遠端擴充功能主機未啟動，則遠端擴充功能主機記錄檔未建立，且不會顯示在輸出檢視中。這仍然是有助於包含在您的問題中的資訊。

遠端問題和意見反應資源

我們有多種其他遠端資源

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