使用 SSH 進行遠端開發

Name: Visual Studio Code
Author: Microsoft

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

您的本地機器不需要存放任何原始程式碼即可獲得這些優勢，因為該擴充功能會直接在遠端機器上執行指令和其他擴充功能。此擴充功能會在遠端作業系統上安裝 VS Code Server；該伺服器與遠端作業系統上現有的任何 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-bit)。
ARMv8l (AArch64) Ubuntu 18.04+ (64-bit)。
使用官方 OpenSSH Server 的 Windows 10 / Server 2016/2019 (1803+)。
macOS 10.14+ (Mojave) SSH 主機，且需啟用遠端登入。
遠端主機至少需要 1 GB RAM，建議至少具備 2 GB RAM 和 2 核心 CPU。

其他基於 glibc 的 Linux 發行版（適用於 x86_64、ARMv7l 與 ARMv8l）若具備必要條件應可運作。請參閱 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 的說明進行設定，或在 Azure 上建立虛擬機器。
選用：如果您的 Linux 或 macOS SSH 主機將同時由多位使用者存取，請考慮在 VS Code 使用者設定中啟用 Remote.SSH: Remote Server Listen On Socket 以提高安全性。

在設定編輯器中

詳細資訊請參閱提示與技巧文章。
選用：雖然支援基於密碼的驗證，但我們建議為您的主機設定基於金鑰的驗證 (key-based authentication)。詳細資訊請參閱提示與技巧文章。

連線到遠端主機

若要首次連線到遠端主機，請執行下列步驟：

請從終端機/PowerShell 視窗執行以下指令，並將 user@hostname 取代為適當的值，以驗證您是否能連線到 SSH 主機。
```
ssh user@hostname
# Or for Windows when using a domain / AAD account
ssh user@domain@hostname
```
在 VS Code 中，從命令面板（F1 或 ⇧⌘P）選取 Remote-SSH: Connect to Host...，並使用與步驟 1 相同的 user@hostname。
如果 VS Code 無法自動偵測您連線的伺服器類型，系統將會要求您手動選取。

一旦選取平台，它將會儲存在 VS Code 設定的 remote.SSH.remotePlatform 屬性中，以便您隨時進行變更。
片刻後，VS Code 將會連線到 SSH 伺服器並完成自我設定。VS Code 會透過進度通知讓您了解最新狀態，您也可以在 Remote - SSH 輸出頻道中查看詳細記錄。

提示：連線中斷或失敗？請參閱疑難排解提示以獲取解決常見問題的資訊。

如果您看到有關 SSH 檔案權限的錯誤，請參閱修正 SSH 檔案權限錯誤章節。
連線成功後，您會處於空白視窗中。您可以隨時參考狀態列來查看目前連線的主機。

在連線狀態下，點擊狀態列項目將會提供遠端指令清單。
接著，您可以像在本地端一樣，使用 File > Open... 或 File > Open Workspace... 開啟遠端機器上的任何資料夾或工作區！

從這裡開始，安裝您想使用的任何擴充功能，並開始編輯程式碼！

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

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

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

執行方式如下：

遵循在遠端主機上安裝 Docker，並在本地安裝 VS Code 與 Dev Containers 擴充功能的安裝步驟。
選用：設定 SSH 基於金鑰的驗證，這樣您就不需要多次輸入密碼。
遵循 Remote - SSH 擴充功能的快速入門指南來連線到主機並開啟資料夾。
使用命令面板中的 Dev Containers: Reopen in Container 指令（F1 或 ⇧⌘P）。

其餘的 Dev Containers 快速入門內容均適用。您可以透過其官方文件進一步了解 Dev Containers 擴充功能。如果此模式不符合您的需求，您也可以參閱在遠端 Docker 主機上進行開發文章以了解其他選項。

中斷與遠端主機的連線

當您完成遠端主機上的編輯工作後，若要關閉連線，請選擇 File > Close Remote Connection。預設設定未包含此指令的鍵盤快速鍵。您也可以直接關閉 VS Code 來結束遠端連線。

記憶主機與進階設定

如果您有一組經常使用的主機，或需要使用額外選項連線到某個主機，您可以將它們加入遵循 SSH 設定檔格式的本地檔案中。

為了方便設定，此擴充功能可以引導您加入主機，而無需手動編輯此檔案。

首先，從命令面板中選取 Remote-SSH: Add New SSH Host...（F1 或 ⇧⌘P），或按一下「活動列」中 SSH Remote Explorer 的 Add New 圖示。

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 設定檔格式所支援的內容，這僅是一個範例。

此後，當您從命令面板選取 Remote-SSH: Connect to Host...（F1 或 ⇧⌘P）或在 Remote Explorer 的 SSH Targets 區段中時，該主機將會出現在主機清單中。

SSH targets in the Remote Explorer

Remote Explorer 允許您在遠端主機上開啟新的空白視窗，或直接開啟之前開啟過的資料夾。展開主機並點擊您想要開啟的資料夾旁的 Open Folder 圖示即可。

Remote Explorer open folder

管理擴充功能

VS Code 在兩個位置之一執行擴充功能：本地端（UI/客戶端）或遠端（SSH 主機）。雖然影響 VS Code UI 的擴充功能（如佈景主題和程式碼片段）會安裝在本地，但大多數擴充功能將駐留在 SSH 主機上。這能確保您擁有流暢的體驗，並允許您從本地機器為 SSH 主機上的特定工作區安裝任何所需的擴充功能。如此一來，即使在不同的機器上，您也可以從上次中斷的地方繼續工作，且擴充功能依然完整。

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

您的遠端 SSH 主機將會有一個類別。

Workspace Extension Category

同時還有一個 Local - Installed (本地已安裝) 類別。

Local Extension Category

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

實際需要在遠端執行但安裝在本地的擴充功能，會在 Local - Installed 類別中顯示為灰色且停用。選取 Install 即可將該擴充功能安裝到您的遠端主機上。

Disabled Extensions w/Install Button

您也可以前往擴充功能檢視，點擊 Local - Installed 標題列右側的雲端按鈕，選擇 Install Local Extensions in SSH: {Hostname}，將所有本地安裝的擴充功能安裝到 SSH 主機上。這將顯示一個下拉選單，讓您選擇要安裝到 SSH 主機上的本地擴充功能。

「始終安裝 (Always installed)」的擴充功能

如果您希望在任何 SSH 主機上都始終安裝某些擴充功能，可以使用 settings.json 中的 remote.SSH.defaultExtensions 屬性來指定。例如，若您想安裝 GitLens 和 Resource Monitor 擴充功能，請按如下方式指定其 ID：

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

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

擴充功能通常設計與測試為僅在本地或僅在遠端執行，而非兩者皆可。不過，如果擴充功能支援，您可以在 settings.json 檔案中強制其在特定位置執行。

例如，下方的設定將強制 Container Tools 擴充功能在本地執行，並將 Remote - SSH: Editing Configuration Files 擴充功能改為在遠端執行，取代其預設值：

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

將 "workspace" 改為 "ui" 值將強制擴充功能在本地 UI/客戶端執行。除非擴充功能文件中另有說明，否則此設定通常僅應用於測試，因為它可能會導致擴充功能崩潰。詳細資訊請參閱支援遠端開發文章。

轉送連接埠 / 建立 SSH 通道

有時在開發時，您可能需要存取遠端機器上未公開暴露的連接埠。有兩種方式可以使用 SSH 通道將所需的遠端連接埠「轉送」到您的本地機器。

暫時轉送連接埠

連線到主機後，如果您想在該工作階段期間暫時轉送新的連接埠，請從命令面板選取 Forward a Port（F1 或 ⇧⌘P），或在 Ports view 中選擇 Add Port 按鈕。您可以在底部面板中看到 Ports 檢視，或執行 Ports: Focus on Ports View 指令。

Forward port button

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

Adding a new port

通知會告訴您應該使用哪個本地連接埠（localhost）來存取遠端連接埠。例如，如果您轉送了一個監聽在 3000 連接埠的 HTTP 伺服器，通知可能會顯示因為 3000 已被佔用，所以它被對應到 localhost 的 4123 連接埠。您隨後可以使用 https://:4123 連線到此遠端 HTTP 伺服器。

如果您以後需要存取此資訊，可以在 Remote Explorer 的 Forwarded Ports 區段中找到。

如果您希望 VS Code 記住您已轉送的任何連接埠，請在設定編輯器（⌘,）中勾選 Remote: Restore Forwarded Ports，或在 settings.json 中設定 "remote.restoreForwardedPorts": true。

Restore forwarded ports setting

更改通道上的本地連接埠

如果您希望通道的本地連接埠與遠端伺服器不同，可以透過 Forwarded Ports 面板進行更改。

以滑鼠右鍵點擊您想要修改的通道，然後在內容選單中選取 Change Local Address Port。

Change Local Address Port

永久轉送連接埠

如果您有始終想要轉送的連接埠，可以在用於記憶主機與進階設定的同一個 SSH 設定檔中使用 LocalForward 指令。

例如，如果您想要轉送連接埠 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 中開啟的任何終端機視窗（Terminal > New Terminal）都會自動在遠端主機上執行，而非本地。

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

Using the code CLI

在 SSH 主機上進行偵錯

連線到遠端主機後，您可以使用 VS Code 的偵錯器，方式與在本地執行應用程式時相同。例如，如果您在 launch.json 中選取一個啟動設定並開始偵錯（F5），應用程式將會在遠端主機上啟動，並將偵錯器附加到其上。

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

SSH 主機特定設定

當您連線到 SSH 主機時，也會重複使用 VS Code 的本地使用者設定。雖然這能讓您的體驗保持一致，但您可能會希望在本地機器與每台主機之間設定不同的選項。幸運的是，一旦連線到主機，您也可以透過從命令面板執行 Preferences: Open Remote Settings 指令（F1 或 ⇧⌘P），或選取設定編輯器中的 Remote 分頁來設定主機特定的設定。只要您連線到該主機，這些設定就會覆寫您現有的任何使用者設定。而工作區設定則會覆寫遠端與使用者設定。

Host-specific settings tab

使用本地工具

Remote - SSH 擴充功能不提供同步原始程式碼或將本地工具與遠端主機內容一起使用的直接支援。不過，使用大多數 Linux 主機皆可運作的常見工具，有兩種方法可以達到目的。具體而言，您可以：

SSHFS 是最方便的選項，且不需要任何檔案同步。不過，效能會比透過 VS Code 操作慢得多，因此最適合用於單一檔案編輯與上傳/下載內容。如果您需要使用會同時大量讀取/寫入檔案的應用程式（如本地版本控制工具），rsync 是更好的選擇。

已知限制

Remote - SSH 限制

建議使用基於金鑰的驗證。為替代驗證方法輸入的密碼與其他權杖不會被儲存。
不支援 Alpine Linux 和非 glibc 的 Linux SSH 主機。
較舊的（社群支援）Linux 發行版需要變通方法來安裝必要的先決條件。
不支援 Windows 上的 PuTTY。
如果您使用 SSH 複製 Git 儲存庫，且您的 SSH 金鑰有密碼（passphrase），VS Code 的提取與同步功能在遠端執行時可能會當機。解決方法是使用沒有密碼的 SSH 金鑰、透過 HTTPS 複製，或從命令列執行 git push。
本地代理伺服器設定不會在遠端主機上重複使用，這可能會導致擴充功能無法運作，除非在遠端主機上設定了適當的代理資訊（例如具有適當代理資訊的全域 HTTP_PROXY 或 HTTPS_PROXY 環境變數）。
請參閱此處以取得與 SSH 相關的活躍問題清單。

Container Tools 擴充功能限制

如果您從 WSL、Remote - Tunnels 或 Remote - SSH 視窗使用 Container Tools 或 Kubernetes 擴充功能，在 Container Explorer 或 Kubernetes 檢視中使用 Attach Visual Studio Code 內容選單操作時，將會再次要求您從可用容器中進行選擇。

擴充功能限制

許多擴充功能無需修改即可在遠端 SSH 主機上運作。但在某些情況下，特定功能可能需要進行調整。如果您遇到擴充功能問題，有一份常見問題與解決方案摘要，您在回報問題時可以提供給擴充功能開發者參考。

此外，安裝在 ARMv7l (AArch32) / ARMv8l (AArch64) 裝置上的某些擴充功能可能無法運作，因為擴充功能中的原生模組或執行環境僅支援 x86_64。在這些情況下，擴充功能需要透過編譯/包含適用於 ARMv7l / ARMv8l 的二進位檔來加入支援。

常見問題

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

詳細資訊請參閱安裝支援的 SSH 客戶端。

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

詳細資訊請參閱安裝支援的 SSH 伺服器，以了解如何為您的主機設定 SSH 伺服器。

可以，系統通常會自動提示您輸入權杖或密碼。不過，由於密碼不會被儲存，使用基於金鑰的驗證通常會更方便。

如何修正關於「bad permissions」（權限錯誤）的 SSH 錯誤？

詳細資訊請參閱修正 SSH 檔案權限錯誤以解決此類問題。

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

大多數 Linux 發行版不需要額外的相依套件安裝步驟。對於 SSH，Linux 主機需要安裝 Bash (/bin/bash)、tar 以及 curl 或 wget，某些精簡版發行版可能缺少這些工具。遠端開發還需要核心 >= 3.10、glibc >= 2.17、libstdc++ >= 3.4.18。目前僅支援基於 glibc 的發行版，因此無法支援 Alpine Linux。

詳細資訊請參閱 Linux 必要條件。

當 VS Code Server 在遠端機器/虛擬機器上執行時，連線需求為何？

安裝 VS Code Server 需要您的本地機器具有連線到以下網址的對外 HTTPS (連接埠 443) 能力：

update.code.visualstudio.com
vscode.download.prss.microsoft.com

預設情況下，Remote - SSH 會嘗試在遠端主機上直接下載，如果失敗，則會在連線建立後改為從本地下載 VS Code Server 再傳輸到遠端。您可以透過 remote.SSH.localServerDownload 設定來變更此行為，改為始終在本地下載後傳輸，或完全不在本地下載。

您可以使用 Extensions: Install from VSIX... 指令手動離線安裝擴充功能。但如果您使用擴充功能面板來安裝擴充功能，您的本地機器和 VS Code Server 伺服器將需要對外 HTTPS (連接埠 443) 存取權限：

marketplace.visualstudio.com
*.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 模組或執行環境，在某些情況下可能需要進行調整。我們建議您測試您的擴充功能，以確保無需更新。詳細資訊請參閱支援遠端開發。

問題或意見回饋

請參閱提示與技巧或常見問題 (FAQ)。
在 Stack Overflow 上搜尋。
提出功能需求或回報問題。
為我們的文件或 VS Code 本身做出貢獻。
詳細資訊請參閱我們的 CONTRIBUTING 指南。

4/8/2026