參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

使用 SSH 進行遠端開發

Visual Studio Code 遠端 - 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 的 x86_64、ARMv7l (AArch32) 和 ARMv8l (AArch64) Linux 發行版如果具備所需的先決條件，應該也能工作。有關先決條件以及讓社群支援的發行版正常執行的提示，請參閱使用 Linux 進行遠端開發文章。

雖然支援 ARMv7l (AArch32) 和 ARMv8l (AArch64)，但由於擴充套件中使用了 x86 本機程式碼，安裝在這些裝置上的一些擴充套件可能無法工作。

安裝

要開始，你需要：

  1. 安裝一個OpenSSH 相容的 SSH 客戶端（如果尚未安裝）。

  2. 安裝Visual Studio Code或Visual Studio Code Insiders。

  3. 安裝Remote-SSH 擴充套件。如果你計劃在 VS Code 中使用其他遠端擴充套件，可以選擇安裝Remote Development 擴充套件包。

SSH 主機設定

  1. 如果你尚未設定 SSH 主機，請按照Linux、Windows 10 / Server (1803+) 或 macOS SSH 主機的說明進行操作，或者在 Azure 上建立虛擬機器。

  2. 可選：如果你的 Linux 或 macOS SSH 主機將同時被多個使用者訪問，請考慮在 VS Code 使用者設定中啟用 Remote.SSH: Remote Server Listen On Socket 以提高安全性。

    在設定編輯器中

    Listen on socket VS Code setting

    有關詳細資訊，請參閱提示和技巧文章。

  3. 可選：雖然支援基於密碼的身份驗證，但我們建議為你的主機設定基於金鑰的身份驗證。有關詳細資訊，請參閱提示和技巧文章。

連線到遠端主機

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

  1. 透過從終端/PowerShell 視窗執行以下命令來驗證你是否可以連線到 SSH 主機，並相應地替換 user@hostname。

    ssh user@hostname
# Or for Windows when using a domain / AAD account
ssh user@domain@hostname

  2. 在 VS Code 中，從命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）中選擇 Remote-SSH: Connect to Host...，並使用與步驟 1 中相同的 user@hostname。

    Illustration of user@host input box

  3. 如果 VS Code 無法自動檢測你正在連線的伺服器型別，系統將要求你手動選擇型別。

    Illustration of platform selection

    一旦你選擇了一個平臺，它將儲存在 VS Code 設定中的 remote.SSH.remotePlatform 屬性下，以便你可以隨時更改它。

  4. 稍等片刻，VS Code 將連線到 SSH 伺服器並自行設定。VS Code 將透過進度通知讓你保持最新狀態，你可以在 Remote - SSH 輸出通道中檢視詳細日誌。

    提示：連線掛起或失敗？有關解決常見問題的資訊，請參閱故障排除提示。

    如果你看到有關 SSH 檔案許可權的錯誤，請參閱有關修復 SSH 檔案許可權錯誤的部分。

  5. 連線後，你將進入一個空視窗。你可以隨時參考狀態列以檢視你連線到的主機。

    SSH Status bar item

    單擊狀態列項將在你連線時提供遠端命令列表。

  6. 然後，你可以使用 檔案 > 開啟... 或 檔案 > 開啟工作區... 在遠端機器上開啟任何資料夾或工作區，就像在本地一樣！

    File Open on a remote SSH host

從這裡，安裝你希望在連線到主機時使用的任何擴充套件，並開始編輯！

注意：在 ARMv7l / ARMv8l glibc SSH 主機上，某些擴充套件可能由於擴充套件內部的 x86 編譯原生代碼而無法工作。

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

如果你使用的是 Linux 或 macOS SSH 主機，你可以同時使用 Remote - SSH 和 開發容器 擴充套件，在容器中開啟遠端主機上的資料夾。你甚至無需在本地安裝 Docker 客戶端。

操作步驟如下：

  1. 按照安裝步驟在你的遠端主機上安裝 Docker，並在本地安裝 VS Code 和開發容器擴充套件。
  2. 可選： 設定 SSH 基於金鑰的身份驗證到伺服器，這樣你就不需要多次輸入密碼。
  3. 按照 Remote - SSH 擴充套件的快速入門連線到主機並在那裡開啟一個資料夾。
  4. 從命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用 開發容器：在容器中重新開啟 命令。

開發容器快速入門的其餘部分按原樣適用。你可以在開發容器擴充套件的文件中瞭解更多資訊。如果此模型不符合你的需求，你還可以檢視在遠端 Docker 主機上開發文章中的其他選項。

斷開與遠端主機的連線

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

記住主機和高階設定

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

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

首先從命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）中選擇 Remote-SSH: Add New SSH Host...，或單擊活動欄中 SSH 遠端資源管理器中的 新增新 圖示。

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...，或在遠端資源管理器的 SSH 目標部分中，該主機將出現在主機列表中。

SSH targets in the 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 擴充套件，請按如下方式指定它們的擴充套件 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: Focus on Ports View。

Forward port button

系統會要求你輸入要轉發的埠，你可以為其指定一個名稱。

Adding a new port

一條通知會告訴你訪問遠端埠應使用的本地主機埠。例如，如果你轉發了一個監聽埠 3000 的 HTTP 伺服器，通知可能會告訴你它被對映到本地主機上的埠 4123，因為 3000 已經被佔用。然後你就可以使用 https://:4123 連線到這個遠端 HTTP 伺服器。

如果你以後需要訪問，這些資訊在遠端資源管理器的已轉發埠部分中也可用。

如果你希望 VS Code 記住你已轉發的任何埠，請在設定編輯器（⌘, (Windows, Linux Ctrl+,)）中勾選 Remote: Restore Forwarded Ports，或在 settings.json 中設定 "remote.restoreForwardedPorts": true。

Restore forwarded ports setting

更改隧道的本地埠

如果你希望隧道的本地埠與遠端伺服器的不同，你可以透過已轉發埠面板更改此設定。

右鍵單擊要修改的隧道，然後在上下文選單中選擇更改本地地址埠。

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 中開啟的任何終端視窗（終端 > 新建終端）都將自動在遠端主機上執行，而不是在本地。

你還可以從同一個終端視窗使用 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 命令，或透過在設定編輯器中選擇遠端選項卡來設定主機特定的設定。這些設定將在你連線到主機時覆蓋任何已有的使用者設定。工作區設定將覆蓋遠端和使用者設定。

Host-specific settings tab

使用本地工具

Remote - SSH 擴充套件不直接支援原始碼同步或使用本地工具處理遠端主機上的內容。但是，有兩種方法可以使用適用於大多數 Linux 主機的常用工具來完成此操作。具體來說，你可以：

  1. 使用 SSHFS 掛載遠端檔案系統.
  2. 使用 rsync 將檔案同步到/從遠端主機同步到你的本地機器.

SSHFS 是最方便的選擇，不需要任何檔案同步。然而，效能將明顯低於透過 VS Code 工作，因此最適合用於單檔案編輯和上傳/下載內容。如果你需要使用同時批次讀/寫多個檔案的應用程式（如本地原始碼控制工具），rsync 是更好的選擇。

已知限制

遠端 - SSH 限制

  • 推薦使用基於金鑰的身份驗證。為其他身份驗證方法輸入的密碼和其他令牌不會被儲存。
  • 不支援 Alpine Linux 和非 glibc 的 Linux SSH 主機。
  • 較舊的（社群支援的）Linux 發行版需要變通方法才能安裝所需的先決條件。
  • Windows 上不支援 PuTTY。
  • 如果你使用 SSH 克隆 Git 倉庫，並且你的 SSH 金鑰有密碼短語，VS Code 的拉取和同步功能在遠端執行時可能會掛起。請使用不帶密碼短語的 SSH 金鑰，使用 HTTPS 克隆，或者從命令列執行 git push 來解決此問題。
  • 本地代理設定不會在遠端主機上重複使用，這可能會阻止擴充套件工作，除非在遠端主機上配置了適當的代理資訊（例如，帶有適當代理資訊的全域性 HTTP_PROXY 或 HTTPS_PROXY 環境變數）。
  • 請參閱此處，瞭解與 SSH 相關的活動問題列表。

容器工具擴充套件限制

如果您正在從 WSL、Remote - Tunnels 或 Remote - SSH 視窗使用 Container Tools 或 Kubernetes 擴充套件，則在容器資源管理器或 Kubernetes 檢視中使用 Attach Visual Studio Code 上下文選單操作將要求第二次從可用容器中進行選擇。

擴充套件限制

許多擴充套件無需修改即可在遠端 SSH 主機上工作。然而，在某些情況下，某些功能可能需要更改。如果你遇到擴充套件問題，有一份常見問題和解決方案的總結，你可以在報告問題時向擴充套件作者提及。

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

常見問題

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

有關詳細資訊，請參閱安裝受支援的 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設定來更改此行為，以始終在本地下載然後傳輸，或者從不進行本地下載。

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

問題或反饋

09/11/2025