使用 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 位元)。
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 中，從命令面板 (F1、⇧⌘P (Windows、Linux Ctrl+Shift+P)) 選取 Remote-SSH: Connect to Host... (Remote-SSH：連線到主機...)，並使用與步驟 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 和開發容器擴充功能結合使用，以在容器內開啟遠端主機上的資料夾。您甚至不需要在本機安裝 Docker 用戶端。

若要執行此操作：

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

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

中斷與遠端主機的連線

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

記住主機和進階設定

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

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

首先從命令面板 (F1、⇧⌘P (Windows、Linux Ctrl+Shift+P)) 選取 Remote-SSH: Add New SSH Host... (Remote-SSH：新增 SSH 主機...)，或按一下活動列中 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 組態檔格式支援的任何內容手動編輯此檔案，因此這只是一個範例。

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

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 主機上安裝所有本機安裝的擴充功能。這會顯示一個下拉式清單，您可以在其中選取要在 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 - SSH：編輯組態檔) 擴充功能在遠端執行，而不是預設值：

"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 a Port (轉送連接埠)，或選取 Ports (連接埠) 檢視中的 Add Port (新增連接埠) 按鈕。您可以在底部面板中看到「連接埠」檢視，或執行命令 Ports: Focus on Ports View (連接埠：聚焦於「連接埠」檢視)。

Forward port button

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

Adding a new port

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

如果您稍後需要存取此資訊，則此資訊也位於 Remote Explorer (遠端瀏覽器) 的 Forwarded Ports (已轉送連接埠) 區段中。

如果您希望 VS Code 記住您已轉送的任何連接埠，請在設定編輯器 (⌘, (Windows、Linux Ctrl+,)) 中勾選 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 的本機使用者設定。雖然這可讓您的使用者體驗保持一致，但您可能想要在本機機器和每個主機之間變更其中一些設定。幸運的是，連線到主機後，您也可以透過從命令面板 (F1、⇧⌘P (Windows、Linux Ctrl+Shift+P)) 執行 Preferences: Open Remote Settings (偏好設定：開啟遠端設定) 命令，或在「設定」編輯器中選取 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 金鑰有密碼，則 VS Code 的提取和同步功能在遠端執行時可能會停滯。請使用沒有密碼的金鑰、使用 HTTPS 複製，或從命令列執行 git push 以解決此問題。
本機 Proxy 設定不會在遠端主機上重複使用，這可能會阻止擴充功能運作，除非在遠端主機上設定適當的 Proxy 資訊 (例如，具有適當 Proxy 資訊的全域 HTTP_PROXY 或 HTTPS_PROXY 環境變數)。
請參閱此處以取得與 SSH 相關的現有問題清單。

Docker 擴充功能限制

如果您從 WSL、Remote - Tunnels 或 Remote - SSH 視窗使用 Docker 或 Kubernetes 擴充功能，則在 Docker 或 Kubernetes 檢視中使用 Attach Visual Studio Code (附加 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。

請參閱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 設定變更此行為，以永遠在本機下載然後傳輸，或永遠不在本機下載。

您可以使用 Extensions: Install from VSIX... (擴充功能：從 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 Remote Development 的設計並未考慮此使用案例，因為它否定了效能和使用者體驗優勢。

但是，此使用案例通常可以透過結合 SFTP 等擴充功能與 Node.js、Python、C# 或其他語言的遠端偵錯功能來處理。

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

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

問題或意見反應

請參閱提示與技巧或常見問題。
在 Stack Overflow 上搜尋。
新增功能要求或回報問題。
貢獻我們的文件或VS Code 本身。
請參閱我們的貢獻指南以了解詳細資訊。

04/03/2025