使用 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 Server。
macOS 10.14+ (Mojave) SSH 主機，已啟用遠端登入。
遠端主機需要 1 GB RAM，但建議至少 2 GB RAM 和 2 核 CPU。

x86_64、ARMv7l (AArch32) 和 ARMv8l (AArch64) 的其他 glibc 發行版，如果滿足所需的前提條件，也應該可以工作。請參閱 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 以提高安全性。

在“設定”編輯器中

有關詳細資訊，請參閱技巧與竅門文章。
可選： 雖然支援基於密碼的身份驗證，但我們建議為您的主機設定**基於金鑰的身份驗證**。有關詳細資訊，請參閱技巧與竅門文章。

連線到遠端主機

首次連線到遠端主機，請按照以下步驟操作

透過從終端/PowerShell 視窗執行以下命令，驗證您是否可以連線到 SSH 主機，並根據需要替換 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...，並使用與步驟 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 擴充套件的快速入門，連線到主機並在那裡開啟一個資料夾。
從命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用 開發容器：在容器中重新開啟 命令。

其餘的 Dev Containers 快速入門部分直接適用。您可以在 Dev Containers 擴充套件文件中瞭解更多關於該擴充套件的資訊。如果您覺得此模型不符合您的需求，還可以檢視在遠端 Docker 主機上開發文章以獲取其他選項。

斷開與遠端主機的連線

完成在遠端主機上編輯檔案後，要關閉連線，請選擇 File > Close Remote Connection 以斷開與主機的連線。預設配置不包含此命令的鍵盤快捷鍵。您也可以簡單地退出 VS Code 來關閉遠端連線。

記住主機和高階設定

如果您有經常使用的主機集，或者需要使用一些額外的選項連線到主機，可以將它們新增到遵循 SSH 配置檔案格式的本地檔案中。

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

首先，從命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）選擇 Remote-SSH: Add New SSH Host...，或單擊活動欄中 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 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

您還可以透過轉到“擴充套件”檢視並選擇Install Local Extensions in SSH: {Hostname}（使用Local - Installed標題欄右側的雲按鈕）來在 SSH 主機上安裝所有本地安裝的擴充套件。這將顯示一個下拉選單，您可以在其中選擇要安裝到 SSH 主機的本地擴充套件。

"始終安裝"的擴充套件

如果您希望某些擴充套件始終安裝在任何 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" ]
}

值為 "ui" 而不是 "workspace" 將強制擴充套件在本地 UI/客戶端側執行。通常，除非擴充套件文件中有其他說明，否則這隻應用於測試，因為它**可能導致擴充套件損壞**。有關詳細資訊，請參閱支援遠端開發文章。

埠轉發 / 建立 SSH 隧道

有時，在開發過程中，您可能需要訪問遠端計算機上未公開的埠。使用“SSH 隧道”可以做到這一點，它會將所需的遠端埠“轉發”到您的本地計算機。有兩種方法可以實現這一點。

臨時轉發埠

連線到主機後，如果您想在會話期間**臨時轉發**新埠，請從命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）選擇 Forward a Port，或者在Ports view中選擇Add Port按鈕。您可以在底部面板中看到“Ports view”，或者執行命令 Ports: Focus on Ports View。

Forward port button

系統將要求您輸入要轉發的埠，並可以為其指定名稱。

Adding a new port

通知將告知您應使用哪個 localhost 埠來訪問遠端埠。例如，如果您轉發了一個監聽埠 3000 的 HTTP 伺服器，通知可能會告知它已被對映到 localhost 的埠 4123，因為 3000 埠已被使用。然後，您可以使用 https://: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 主機特定設定

VS Code 的本地使用者設定在連線到 SSH 主機時也會被重用。雖然這能保持您的使用者體驗一致，但您可能希望在本地計算機和每個主機之間調整某些設定。幸運的是，連線到主機後，您可以透過執行命令面板（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 的拉取和同步功能在遠端執行時可能會掛起。請使用不帶密碼短語的 SSH 金鑰，使用 HTTPS 克隆，或者從命令列執行 git push 來解決此問題。
遠端主機不重用本地代理設定，這可能會阻止擴充套件程式工作，除非在遠端主機上配置了相應的代理資訊（例如，具有適當代理資訊的全域性 HTTP_PROXY 或 HTTPS_PROXY 環境變數）。
有關 SSH 的活動問題列表，請參閱此處。

容器工具擴充套件限制

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

擴充套件限制

許多擴充套件在遠端 SSH 主機上無需修改即可工作。但是，在某些情況下，特定功能可能需要更改。如果您遇到擴充套件問題，有一個常見問題和解決方案彙總，您可以在報告問題時提供給擴充套件作者。

此外，在 ARMv7l (AArch32) / ARMv8l (AArch64) 裝置上安裝的某些擴充套件可能無法正常工作，因為擴充套件中包含的原生模組或執行時僅支援 x86_64。在這種情況下，擴充套件需要透過編譯/包含 ARMv7l / ARMv8l 的二進位制檔案來選擇支援這些平臺。

常見問題

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

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

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

有關為您的主機設定 SSH 伺服器的詳細資訊，請參閱安裝支援的 SSH 伺服器。

是的，系統應自動提示您輸入令牌或密碼。但是，密碼不會被儲存，因此使用基於金鑰的身份驗證通常更方便。

我如何修復有關“許可權錯誤”的 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 Remote Development 不是為這種情況設計的，因為它會削弱效能和使用者體驗優勢。

但是，這種情況通常可以透過結合使用 SFTP 等擴充套件以及用於 Node.js、Python、C# 等的遠端除錯功能來處理。

作為擴充套件作者，我需要做什麼？

VS Code 擴充套件 API 抽象了本地/遠端細節，因此大多數擴充套件無需修改即可工作。但是，考慮到擴充套件可以使用它們想要的任何節點模組或執行時，有時可能需要進行調整。我們建議你測試你的擴充套件，以確保不需要更新。有關詳細資訊，請參閱支援遠端開發。

問題或反饋

請參閱技巧與竅門或 FAQ。
在 Stack Overflow 上搜索。
新增功能請求或報告問題。
為我們的文件或VS Code 本身做出貢獻。
請參閱我們的貢獻指南瞭解詳細資訊。

12/10/2025