使用 SSH 進行遠端開發

Name: Visual Studio Code
Author: Microsoft

Visual Studio Code Remote - SSH 擴充功能可讓您在任何執行 SSH 伺服器的遠端電腦、虛擬機器或容器上開啟遠端資料夾，並充分利用 VS Code 的功能集。連線到伺服器後，您可以與遠端檔案系統上任何位置的檔案和資料夾互動。

由於擴充功能直接在遠端電腦上執行命令和其他擴充功能，因此您的本機電腦上不需要有任何原始碼即可獲得這些優點。此擴充功能將在遠端 OS 上安裝 VS Code Server；此伺服器獨立於遠端 OS 上的任何現有 VS Code 安裝。

SSH Architecture

這讓 VS Code 能夠提供本機品質的開發體驗，包括完整的 IntelliSense (完成項目)、程式碼導覽和偵錯功能，無論您的程式碼託管在何處。

開始使用

注意：檢閱本主題後，您可以開始使用入門的 SSH 教學課程。

系統需求

本機： 也必須安裝支援的 OpenSSH 相容 SSH 用戶端。

遠端 SSH 主機：在下列項目上執行的 SSH 伺服器

x86_64 Debian 8+、Ubuntu 16.04+、CentOS / RHEL 7+。
ARMv7l (AArch32) Raspberry Pi OS (先前稱為 Raspbian) Stretch/9+ (32 位元)。
ARMv8l (AArch64) Ubuntu 18.04+ (64 位元)。
Windows 10 / Server 2016/2019 (1803+) 使用官方 OpenSSH 伺服器。
macOS 10.14+ (Mojave) 具有啟用遠端登入的 SSH 主機。
遠端主機需要 1 GB RAM，但建議至少 2 GB RAM 和 2 核心 CPU。

其他以 glibc 為基礎的 Linux 發行版本 (適用於 x86_64、ARMv7l (AArch32) 和 ARMv8l (AArch64)) 如果具有所需先決條件，應該也能運作。請參閱使用 Linux 進行遠端開發文章，以取得先決條件資訊和讓社群支援的發行版本啟動並執行的秘訣。

雖然 ARMv7l (AArch32) 和 ARMv8l (AArch64) 支援已推出，但由於在擴充功能中使用 x86 原生程式碼，因此安裝在這些裝置上的某些擴充功能可能無法運作。

安裝

若要開始使用，您需要

如果尚未安裝 OpenSSH 相容 SSH 用戶端，請安裝。
安裝 Visual Studio Code 或 Visual Studio Code Insiders。
安裝 Remote-SSH 擴充功能。如果您計劃在 VS Code 中使用其他遠端擴充功能，您可以選擇安裝 Remote Development 擴充功能套件。

SSH 主機設定

如果您沒有設定 SSH 主機，請依照 Linux、Windows 10 / Server (1803+) 或 macOS SSH 主機的指示進行，或在 Azure 上建立 VM。
選用： 如果您的 Linux 或 macOS SSH 主機將同時由多個使用者存取，請考慮在 VS Code 使用者設定中啟用Remote.SSH: Remote Server Listen On Socket，以提升安全性。

在設定編輯器中

如需詳細資訊，請參閱提示與技巧文章。
選用： 雖然支援以密碼為基礎的驗證，但我們建議為主機設定金鑰式驗證。如需詳細資訊，請參閱提示與技巧文章。

連線到遠端主機

若要首次連線到遠端主機，請依照下列步驟進行

確認您可以連線到 SSH 主機，方法是從終端機/PowerShell 視窗執行下列命令，並視需要取代 user@hostname。
```
ssh user@hostname
# Or for Windows when using a domain / AAD account
ssh user@domain@hostname
```
在 VS Code 中，從命令面板選取 Remote-SSH: Connect to Host... (F1，⇧⌘P (Windows、Linux Ctrl+Shift+P))，並使用與步驟 1 中相同的 user@hostname。
如果 VS Code 無法自動偵測您要連線的伺服器類型，系統會要求您手動選取類型。

選取平台後，它將儲存在 VS Code 設定中的 remote.SSH.remotePlatform 屬性下，因此您可以隨時變更它。
稍待片刻，VS Code 將連線到 SSH 伺服器並自行設定。VS Code 將使用進度通知讓您隨時掌握最新狀態，您可以在 Remote - SSH 輸出通道中看到詳細記錄。

提示： 連線停滯或失敗？請參閱疑難排解秘訣，以取得解決常見問題的資訊。

如果您看到有關 SSH 檔案權限的錯誤，請參閱修正 SSH 檔案權限錯誤一節。
連線後，您會看到一個空白視窗。您可以隨時參考狀態列，查看您連線到哪個主機。

按一下狀態列項目會在您連線時提供遠端命令清單。
然後，您可以使用 檔案 > 開啟... 或 檔案 > 開啟工作區... 在遠端電腦上開啟任何資料夾或工作區，就像在本機上一樣！

從這裡，安裝您想要在連線到主機時使用的任何擴充功能，然後開始編輯！

注意： 在 ARMv7l / ARMv8l glibc SSH 主機上，由於擴充功能內有 x86 編譯的原生程式碼，因此某些擴充功能可能無法運作。

在容器中的遠端 SSH 主機上開啟資料夾

如果您使用 Linux 或 macOS SSH 主機，您可以將 Remote - SSH 和 Dev Containers 擴充功能一起使用，以在容器內開啟遠端主機上的資料夾。您甚至不需要在本機上安裝 Docker 用戶端。

若要執行此操作

依照安裝步驟，在遠端主機和本機上的 VS Code 和 Dev Containers 擴充功能上安裝 Docker。
選用： 設定 SSH 金鑰式驗證到伺服器，這樣您就不需要多次輸入密碼。
依照 Remote - SSH 擴充功能的快速入門連線到主機並在那裡開啟資料夾。
從命令面板 (F1，⇧⌘P (Windows、Linux Ctrl+Shift+P)) 使用 Dev Containers: Reopen in Container 命令。

其餘的 Dev Containers 快速入門適用於現狀。您可以在其文件中深入瞭解 Dev Containers 擴充功能。如果此模型不符合您的需求，您也可以參閱在遠端 Docker 主機上開發文章，以取得其他選項。

中斷與遠端主機的連線

若要在完成編輯遠端主機上的檔案時關閉連線，請選擇 檔案 > 關閉遠端連線 以中斷與主機的連線。預設組態不包含此命令的鍵盤快速鍵。您也可以直接結束 VS Code 以關閉遠端連線。

記住主機和進階設定

如果您有一組經常使用的主機，或需要使用一些其他選項連線到主機，您可以將它們新增至遵循 SSH 組態檔格式的本機檔案。

為了簡化設定，擴充功能可以引導您新增主機，而無需手動編輯此檔案。

首先，從命令面板 (F1，⇧⌘P (Windows、Linux Ctrl+Shift+P)) 選取 Remote-SSH: Add New SSH Host...，或按一下活動列中 SSH Remote Explorer 中的新增圖示。

Remote Explorer Add New item

然後，系統會要求您輸入 SSH 連線資訊。您可以輸入主機名稱

Remote Explorer SSH host input

或您將用於從命令列連線到主機的完整 ssh 命令

Remote Explorer SSH command input

最後，系統會要求您選擇要使用的組態檔。如果您想要使用與所列檔案不同的組態檔，您也可以在您的使用者 settings.json 檔案中設定 "remote.SSH.configFile" 屬性。擴充功能會處理其餘部分！

例如，在輸入方塊中輸入 ssh -i ~/.ssh/id_rsa-remote-ssh yourname@remotehost.yourcompany.com 將產生此項目

Host remotehost.yourcompany.com
    User yourname
    HostName another-host-fqdn-or-ip-goes-here
    IdentityFile ~/.ssh/id_rsa-remote-ssh

如需產生此處顯示的金鑰的詳細資訊，請參閱提示與技巧。您可以使用 SSH 組態檔格式支援的任何項目手動編輯此檔案，因此這只是一個範例。

從現在開始，當您從命令面板 (F1，⇧⌘P (Windows、Linux Ctrl+Shift+P)) 選取 Remote-SSH: Connect to Host... 時，或在 Remote Explorer 的 SSH 目標 區段中，主機將會出現在主機清單中。

SSH targets in the Remote Explorer

Remote Explorer 可讓您在遠端主機上開啟新的空白視窗，或直接開啟先前開啟的資料夾。展開主機，然後按一下您想要在主機上開啟的資料夾旁邊的 開啟資料夾 圖示。

Remote Explorer open folder

管理擴充功能

VS Code 在兩個位置之一執行擴充功能：本機 UI/用戶端，或遠端 SSH 主機。雖然影響 VS Code UI 的擴充功能 (例如佈景主題和程式碼片段) 是在本機安裝，但大多數擴充功能將駐留在 SSH 主機上。這可確保您擁有順暢的體驗，並讓您從本機電腦在 SSH 主機上安裝給定工作區所需的任何擴充功能。這樣一來，您可以從不同的電腦接續您上次中斷的地方，並完整保留您的擴充功能。

如果您從擴充功能檢視安裝擴充功能，它將會自動安裝在正確的位置。安裝完成後，您可以根據類別群組判斷擴充功能的安裝位置。

將會有遠端 SSH 主機的類別

Workspace Extension Category

以及 本機 - 已安裝 類別

Local Extension Category

注意： 如果您是擴充功能作者，並且發現您的擴充功能無法正常運作或安裝在錯誤的位置，請參閱支援遠端開發以取得詳細資訊。

實際上需要在遠端執行的本機擴充功能將在 本機 - 已安裝 類別中顯示為灰色並停用。選取安裝以在遠端主機上安裝擴充功能。

Disabled Extensions w/Install Button

您也可以在 SSH 主機上安裝所有本機安裝的擴充功能，方法是前往擴充功能檢視，然後使用 本機 - 已安裝 標題列右側的雲端按鈕，選取 在 SSH 中安裝本機擴充功能: {主機名稱}。這會顯示一個下拉式清單，您可以在其中選取要在 SSH 主機上安裝的本機安裝擴充功能。

「永遠安裝」的擴充功能

如果有些擴充功能您希望永遠安裝在任何 SSH 主機上，您可以使用 settings.json 中的 remote.SSH.defaultExtensions 屬性來指定要安裝的擴充功能。例如，如果您想要安裝 GitLens 和 Resource Monitor 擴充功能，請如下所示指定其擴充功能識別碼

"remote.SSH.defaultExtensions": [
    "eamodio.gitlens",
    "mutantdino.resourcemonitor"
]

進階：強制擴充功能在本機/遠端執行

擴充功能通常設計和測試為在本機或遠端執行，而不是兩者兼具。但是，如果擴充功能支援，您可以強制它在您的 settings.json 檔案中的特定位置執行。

例如，以下設定將強制 Docker 擴充功能在本機執行，並強制 Remote - SSH: Editing Configuration Files 擴充功能在遠端執行，而不是其預設值

"remote.extensionKind": {
    "ms-azuretools.vscode-docker": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

值 "ui" 而非 "workspace" 將強制擴充功能在本機 UI/用戶端執行。通常，除非擴充功能的文件中另有說明，否則這應該僅用於測試，因為它可能會破壞擴充功能。如需詳細資訊，請參閱支援遠端開發文章。

轉送連接埠 / 建立 SSH 通道

有時在開發時，您可能需要存取遠端電腦上未公開公開的連接埠。有兩種方法可以使用 SSH 通道來執行此操作，該通道會將所需的遠端連接埠「轉送」到您的本機電腦。

暫時轉送連接埠

連線到主機後，如果您想要在工作階段期間暫時轉送新的連接埠，請從命令面板 (F1，⇧⌘P (Windows、Linux Ctrl+Shift+P)) 選取 轉送連接埠，或選取 連接埠檢視 中的 新增連接埠 按鈕。您可以在底部面板中看到連接埠檢視，或執行命令 連接埠: 焦點在連接埠檢視上。

Forward port button

系統會要求您輸入要轉送的連接埠，您可以為其命名。

Adding a new port

通知會告知您應該使用哪個 localhost 連接埠來存取遠端連接埠。例如，如果您轉送接聽連接埠 3000 的 HTTP 伺服器，通知可能會告知您它已對應到 localhost 上的連接埠 4123，因為 3000 已在使用中。然後，您可以使用 https://127.0.0.1:4123 連線到此遠端 HTTP 伺服器。

如果您稍後需要存取此資訊，相同的資訊可在 Remote Explorer 的 轉送的連接埠 區段中取得。

如果您希望 VS Code 記住您已轉送的任何連接埠，請在設定編輯器 (⌘, (Windows、Linux Ctrl+,)) 中勾選 Remote: 還原轉送的連接埠，或在 settings.json 中設定 "remote.restoreForwardedPorts": true。

Restore forwarded ports setting

變更通道上的本機連接埠

如果您希望通道的本機連接埠與遠端伺服器的連接埠不同，您可以透過 轉送的連接埠 面板變更此設定。

以滑鼠右鍵按一下您要修改的通道，然後在操作功能表中選取 變更本機位址連接埠。

Change Local Address Port

永遠轉送連接埠

如果您有永遠想要轉送的連接埠，您可以使用 LocalForward 指示詞，在您用來記住主機和進階設定的相同 SSH 組態檔中。

例如，如果您想要轉送連接埠 3000 和 27017，您可以如下所示更新檔案

Host remote-linux-machine
    User myuser
    HostName remote-linux-machine.mydomain
    LocalForward 127.0.0.1:3000 127.0.0.1:3000
    LocalForward 127.0.0.1:27017 127.0.0.1:27017

在遠端主機上開啟終端機

從 VS Code 在遠端主機上開啟終端機很簡單。連線後，您在 VS Code 中開啟的任何終端機視窗 (終端機 > 新增終端機) 都將自動在遠端主機上而非在本機上執行。

您也可以從同一個終端機視窗使用 code 命令列，執行許多作業，例如在遠端主機上開啟新的檔案或資料夾。輸入 code --help 以查看可從命令列使用的所有選項。

Using the code CLI

在 SSH 主機上偵錯

連線到遠端主機後，您可以使用 VS Code 的偵錯工具，就像在本機上執行應用程式一樣。例如，如果您在 launch.json 中選取啟動組態，然後開始偵錯 (F5)，應用程式將在遠端主機上啟動，並將偵錯工具附加至其中。

如需在 .vscode/launch.json 中設定 VS Code 偵錯功能的詳細資訊，請參閱偵錯文件。

SSH 主機專用設定

當您連線到 SSH 主機時，也會重複使用 VS Code 的本機使用者設定。雖然這可讓您的使用者體驗保持一致，但您可能想要在本機電腦和每個主機之間變更其中一些設定。幸運的是，連線到主機後，您也可以執行命令面板中的 喜好設定: 開啟遠端設定 命令 (F1，⇧⌘P (Windows、Linux Ctrl+Shift+P)) 或在設定編輯器中選取遠端索引標籤，來設定主機專用設定。每當您連線到主機時，這些設定都會覆寫您已設定的任何使用者設定。而工作區設定將覆寫遠端和使用者設定。

Host-specific settings tab

使用本機工具

Remote - SSH 擴充功能不直接支援同步處理原始碼或搭配使用本機工具與遠端主機上的內容。但是，有兩種方法可以使用常見工具來執行此操作，這些工具適用於大多數 Linux 主機。具體而言，您可以

SSHFS 是最方便的選項，不需要任何檔案同步處理。但是，效能會明顯低於透過 VS Code 工作，因此最適合用於單一檔案編輯和上傳/下載內容。如果您需要使用一次大量讀取/寫入許多檔案的應用程式 (例如本機原始碼控制工具)，rsync 是更好的選擇。

已知限制

Remote - SSH 限制

建議使用金鑰式驗證。為替代驗證方法輸入的密碼和其他權杖不會儲存。
不支援 Alpine Linux 和非 glibc 型 Linux SSH 主機。
較舊 (社群支援) 的 Linux 發行版本需要一些變通方法才能安裝所需的先決條件。
Windows 上不支援 PuTTY。
如果您使用 SSH 複製 Git 存放庫，而且您的 SSH 金鑰有密碼，則 VS Code 的提取和同步功能在遠端執行時可能會停滯。請使用沒有密碼的金鑰、使用 HTTPS 複製，或從命令列執行 git push 以解決此問題。
本機 Proxy 設定不會在遠端主機上重複使用，這可能會阻止擴充功能運作，除非在遠端主機上設定適當的 Proxy 資訊 (例如具有適當 Proxy 資訊的全域 HTTP_PROXY 或 HTTPS_PROXY 環境變數)。
請參閱此處，以取得與 SSH 相關的現有問題清單。

Docker 擴充功能限制

如果您從 WSL、Remote - Tunnels 或 Remote - SSH 視窗使用 Docker 或 Kubernetes 擴充功能，則在 Docker 或 Kubernetes 檢視中使用 附加 Visual Studio Code 操作功能表動作，將會要求您第二次從可用的容器中挑選。

擴充功能限制

許多擴充功能在遠端 SSH 主機上都能運作，而無需修改。但是，在某些情況下，某些功能可能需要變更。如果您遇到擴充功能問題，擴充功能秘訣中摘要說明了一些常見問題和解決方案，您可以在回報問題時向擴充功能作者提及。

此外，由於擴充功能中只有 x86_64 支援的原生模組或執行階段，因此安裝在 ARMv7l (AArch32) / ARMv8l (AArch64) 裝置上的某些擴充功能可能無法運作。在這些情況下，擴充功能需要選擇加入支援這些平台，方法是編譯/包含 ARMv7l / ARMv8l 的二進位檔。

常見問題

如何在 ... 上設定 SSH 用戶端？

如需詳細資訊，請參閱安裝支援的 SSH 用戶端。

如何在 ... 上設定 SSH 伺服器？

如需在主機上設定 SSH 伺服器的詳細資訊，請參閱安裝支援的 SSH 伺服器。

可以，系統應該會自動提示您輸入權杖或密碼。但是，密碼不會儲存，因此使用金鑰式驗證通常更方便。

如何修正有關「權限錯誤」的 SSH 錯誤？

如需解決這些類型錯誤的詳細資訊，請參閱修正 SSH 檔案權限錯誤。

遠端 SSH 主機上需要安裝哪些 Linux 套件/程式庫？

大多數 Linux 發行版本不需要其他相依性安裝步驟。對於 SSH，Linux 主機需要安裝 Bash (/bin/bash)、tar 和 curl 或 wget，而這些公用程式可能在某些精簡的發行版本中遺失。Remote Development 也需要核心 >= 3.10、glibc >=2.17、libstdc++ >= 3.4.18。目前僅支援以 glibc 為基礎的發行版本，因此 Alpine Linux Alpine Linux 也不受支援。

如需詳細資訊，請參閱Linux 先決條件。

VS Code Server 在遠端電腦/VM 上執行時的連線需求為何？

安裝 VS Code Server 需要您的本機電腦具有對下列項目的輸出 HTTPS (連接埠 443) 連線能力

update.code.visualstudio.com
vscode.blob.core.windows.net
*.vo.msecnd.net (Azure CDN)

依預設，Remote - SSH 將嘗試在遠端主機上下載，並在連線建立後回復為在本機下載 VS Code Server 並遠端傳輸。您可以使用 remote.SSH.localServerDownload 設定來變更此行為，以永遠在本機下載然後傳輸，或永遠不要在本機下載。

您可以使用 擴充功能: 從 VSIX 安裝... 命令手動安裝擴充功能，而無需網際網路連線，但如果您使用擴充功能面板安裝擴充功能，則您的本機電腦和 VS Code Server 伺服器將需要對下列項目的輸出 HTTPS (連接埠 443) 存取權

marketplace.visualstudio.com
*.vo.msecnd.net (Azure CDN)
*.gallerycdn.vsassets.io (Azure CDN)

最後，某些擴充功能 (例如 C#) 會從 download.microsoft.com 或 download.visualstudio.microsoft.com 下載次要相依性。其他擴充功能 (例如 Visual Studio Live Share) 可能有其他連線需求。如果您遇到問題，請參閱擴充功能的文件以取得詳細資訊。

伺服器與 VS Code 用戶端之間的所有其他通訊都是透過經過驗證的安全 SSH 通道完成。

我可以在位於遠端 SSH 主機上的原始碼上使用本機工具嗎？

是的。通常這會透過使用 SSHFS 或透過使用 rsync 來取得您本機檔案的副本來完成。SSHFS 掛載遠端檔案系統非常適合需要編輯個別檔案或瀏覽原始碼樹狀結構的情境，且使用時無需同步步驟。然而，它不太適合用於像是原始碼控制工具這種大量管理檔案的工具。在這種情況下，rsync 方法更好，因為您可以在本機取得遠端原始碼的完整副本。詳情請參閱秘訣與技巧。

當我只有 SFTP/FTP 檔案系統存取權限到我的遠端主機（沒有 shell 存取權限）時，我可以使用 VS Code 嗎？

有些雲端平台僅為開發人員提供遠端檔案系統存取權限，而不是直接的 shell 存取權限。VS Code 遠端開發在設計時並未考慮到這種使用情境，因為它會抵銷效能和使用者體驗的優勢。

然而，這種使用情境通常可以透過結合像是 SFTP 擴充功能與遠端偵錯功能來處理，例如 Node.js、Python、C# 或其他語言。

作為擴充功能作者，我需要做些什麼？

VS Code 擴充功能 API 抽象化了本機/遠端細節，因此大多數擴充功能無需修改即可運作。然而，由於擴充功能可以使用任何它們想要的 node 模組或執行階段，因此在某些情況下可能需要進行調整。我們建議您測試您的擴充功能，以確保不需要更新。詳情請參閱支援遠端開發。

問題或意見回饋

請參閱秘訣與技巧或常見問題。
在 Stack Overflow 上搜尋。
新增功能請求或回報問題。
貢獻到我們的文件或 VS Code 本身。
詳情請參閱我們的貢獻指南。

02/06/2025