VS Code Remote SSH 連接遠端 Mac 失敗：2026 排查指南

終端機可以 SSH 連上遠端 Mac，但 VS Code Remote SSH 卡在「正在連接主機」或「初始化 VS Code Server」？

最快解法：先用同一個主機別名執行命令列 SSH，保存 Remote - SSH 輸出日誌，再按網路、認證、VS Code Server、代理與工作區的順序定位；不要一開始反覆重裝擴充功能或刪除遠端目錄。

這篇適合需要從 Windows、Linux 或本地 Mac 進入 macOS 工具鏈的跨平台開發者，也適合維護團隊遠端 Mac 開發節點的 DevOps 與平台工程師。

如果您遇到 VS Code Server 安裝失敗、連線長時間卡住、遠端終端機可用但 Git 或除錯失效，本文會把故障拆成可以觀察、驗證、修復及復測的工程步驟。

「普通終端機可以連線」不等於 VS Code Remote SSH 全鏈路正常。命令列 SSH 主要驗證主機是否可達、SSH 服務是否回應，以及帳戶能否完成認證；VS Code Remote SSH 連線後，還會在遠端環境安裝並啟動 VS Code Server，再透過 SSH 通道讓本機介面操作遠端檔案與程式。Visual Studio Code Remote SSH 官方文件說明了這個連線模型。

請先保留以下四組證據：

• 命令列 SSH：成功或失敗、完整錯誤類型及使用的主機別名。
• VS Code 建立連線：Remote - SSH 輸出頻道的最後一段日誌。
• 遠端 Server：是否完成下載、解壓及啟動。
• 工作區運行：是否能開啟專案、啟動遠端終端機、執行程式命令及開始除錯。

VS Code 可從命令面板執行 Remote-SSH: Show Log 查看連線日誌；若需要收集登入提示或密碼輸入畫面，可暫時啟用 remote.SSH.showLoginTerminal。官方故障排查文件也建議在必要時搭配 remote.SSH.useLocalServer 重新測試。Remote SSH 故障排查文件可作為日誌欄位的對照依據。

先把「主機不可達」與「VS Code 內部初始化失敗」分開。從本機終端機或 PowerShell 執行：

ssh -vvv mac-dev

mac-dev 應該是 VS Code Remote SSH 實際使用的主機別名，而不是另一個手動輸入的 IP 或完整主機名稱。若需要確認別名展開後的設定，可執行：

ssh -G mac-dev

重點不是複製整份輸出，而是核對 user、hostname、連接埠、代理及金鑰來源是否符合預期。OpenSSH 的設定檔可透過 HostName、User 與 IdentityFile 指定實際主機、登入帳戶及私鑰；設定檔的有效路徑與權限也會影響結果。可參考 OpenSSH ssh_config 設定說明。

請依序檢查：

• 名稱解析：用系統現有的 nslookup 或 dig 確認主機名稱能解析；若解析結果不穩定，先處理 DNS 或平台端入口。
• 連接埠可達：Windows 可用 PowerShell 的 Test-NetConnection，macOS 或 Linux 可使用系統提供的連接埠測試工具，確認連線是否逾時。
• SSH 服務回應：Connection timed out 通常先看路由、防火牆或入口策略；Connection refused 則應檢查遠端 SSH 服務是否監聽；主機指紋警告則不要直接忽略，先核對主機是否真的更換。
• macOS 設定：在遠端 Mac 開啟「系統設定」>「一般」>「共享」>「遠端登入」，確認服務啟用，並確認目前帳戶在允許存取清單中。Apple 的官方說明也列出可讓所有使用者登入，或只允許指定使用者。Apple 遠端登入設定指南

若命令列 SSH 已經無法完成登入，先不要在 VS Code 內調整 Server。這時 VS Code 只是把同一個底層可達性問題顯示得更不清楚。

命令列測試必須與 VS Code 使用同一個別名及設定檔。常見錯誤不是私鑰「壞掉」，而是 VS Code 命中了另一個 Host 區段、用了不同的 User，或根本沒有讀取預期的設定檔。

可用下列方式逐項核對：

ssh -G mac-dev
ssh -vvv mac-dev
ssh mac-dev 'printf "remote-shell-ok\n"; command -v bash; echo "$SHELL"'

在輸出中觀察：

• Offering public key 後被拒絕：檢查遠端帳戶的授權金鑰、登入帳戶及金鑰代理。
• identity file ... type -1：通常代表 IdentityFile 路徑不存在或路徑展開不正確。
• Permission denied (publickey)：確認遠端帳戶與私鑰配對，不要只換另一把金鑰碰運氣。
• Bad permissions 或 UNPROTECTED PRIVATE KEY FILE：依本機作業系統收緊私鑰及 .ssh 目錄權限。
• 首次出現主機指紋提示：先在可信管道核對指紋，不要把完整主機地址、私鑰、密碼或權杖貼到公開日誌。

在 Windows、Linux 與 macOS 之間切換時，尤其要留意 VS Code 的 SSH 設定檔位置。可從命令面板執行 Remote-SSH: Open Configuration File...，確認它與本機終端機實際讀取的檔案一致。若金鑰是由 Agent 管理，也應在同一個本機使用者環境確認 Agent 中確實載入了預期私鑰。

當命令列 SSH 成功、VS Code 卻停在初始化，優先查看 Remote - SSH 日誌中的動作位置，而不是直接刪除 ~/.vscode-server。

可把現象分成四類。

下載失敗

Remote SSH 可能嘗試在遠端 Mac 下載 VS Code Server；若遠端沒有外部連線能力，也可能改由本機下載後傳送。官方文件列出的必要下載服務包含 update.code.visualstudio.com 與 vscode.download.prss.microsoft.com，擴充功能安裝則可能需要 Marketplace 及 CDN 連線。

因此要檢查：

• 遠端 Mac 是否能透過 HTTPS 連出；
• 平台防火牆是否阻擋必要網域；
• 遠端 Shell 是否正確繼承 HTTP_PROXY 或 HTTPS_PROXY；
• Proxy 是否只設定在本機，卻沒有設定在遠端工作區環境。

解壓或寫入失敗

如果日誌出現無法建立目錄、寫入檔案或解壓失敗，應檢查遠端家目錄的寫入權限、可用硬碟空間，以及是否有安全政策限制暫存目錄執行。官方排查文件特別提到，若 /tmp 不允許執行安裝腳本，Server 安裝可能會中斷。

此時可先在遠端終端機執行：

pwd
echo "$HOME"
df -h
ls -ld "$HOME" /tmp

這些命令的目的，是確認目前工作目錄、家目錄位置、可用空間與目錄權限；不要把包含帳戶名稱或主機資訊的完整輸出直接貼到公開論壇。

Server 未啟動或殘留

若日誌顯示 Server 已安裝，但啟動後立即停止，可先執行：

• Remote-SSH: Kill VS Code Server on Host...：用於終止目前的 Server 狀態後重新建立。
• Remote-SSH: Uninstall VS Code Server from Host...：會終止 Server 並刪除安裝資料，應在已保存日誌且確認可重新安裝後使用。

解除安裝不是無害的「重新整理」；它會移除遠端 Server 及其相關狀態，遠端擴充功能通常也需要重新部署。因此只有在日誌指向殘留程序或安裝目錄損壞時，才把它列為修復動作。

SSH 通道轉送被拒絕

若輸出出現 administratively prohibited 或類似轉送被拒絕訊息，請檢查遠端 SSH 服務是否允許 TCP forwarding。Remote SSH 依賴已認證的 SSH 通道與轉送機制；若平台政策或 sshd 設定禁止轉送，命令列互動登入仍可能成功，但 VS Code Server 無法被本機介面使用。

連線狀態變綠，只代表 VS Code 已建立某個遠端工作階段，不代表開發環境已驗收完成。Remote SSH 的擴充功能可能分成安裝在本機 UI 端，或安裝在遠端 Mac 的工作區端；需要讀取專案、執行語言服務或呼叫原生依賴的擴充功能，通常必須在遠端一側正確安裝。

請依下列順序復測：

• [ ] 開啟正確的遠端專案資料夾，而不是本機同名資料夾。
• [ ] 在 VS Code 內開啟遠端終端機，執行 pwd、command -v git、echo "$PATH"。
• [ ] 使用與終端機相同的環境執行建置、測試或套件命令。
• [ ] 在擴充功能頁面確認套件安裝於遠端 Mac，而非只有 Local - Installed。
• [ ] 檢查 Apple Silicon 原生依賴是否提供相容版本；若擴充功能內含只支援 x86 的原生模組，連線成功後仍可能啟動失敗。可參考 Apple Silicon 架構相容性說明。
• [ ] 實際啟動除錯、執行 Git 操作及開啟專案需要的本機埠轉送。

Shell 問題很容易被忽略。例如，互動式終端機載入了 .zshrc，但 Server 安裝使用的非互動式 Shell 讀取了另一組啟動檔；若啟動檔輸出歡迎文字、執行互動命令或覆寫 PATH，就可能讓安裝腳本收到非預期內容。應避免在啟動檔中強制切換另一個 Shell，也不要讓登入腳本在非互動連線時輸出大量文字。

為什麼終端機可以 SSH 連線 Mac，但 VS Code Remote SSH 仍然失敗？

因為兩者驗證的範圍不同。終端機成功只代表 SSH 登入完成；VS Code 還要安裝、啟動 VS Code Server，並建立供本機介面使用的轉送通道。請先看 Remote - SSH 日誌，將問題歸入下載、權限、Server 啟動或通道轉送，而不是先重裝擴充功能。

VS Code Server 在遠端 Mac 上安裝卡住時，應先處理什麼？

先核對遠端 Mac 的外部 HTTPS 連線、代理變數、家目錄寫入權限及暫存目錄限制。若日誌只顯示等待輸入，啟用 remote.SSH.showLoginTerminal；若明確指出 Server 殘留，再使用官方提供的終止或解除安裝命令，並準備重新安裝及重新部署遠端擴充功能。

Remote SSH 一直停在正在連接主機時，應該檢查哪些項目？

先用同一個 SSH 別名執行 ssh -vvv 別名。命令列也失敗，就檢查名稱解析、入口連接埠、macOS 遠端登入及帳戶；命令列成功，就檢查 Remote - SSH 日誌、VS Code Server、SSH forwarding、代理和遠端 Shell。不要把「正在連接」視為單一故障。

遠端 Mac 重啟後，VS Code 無法重新連線怎麼辦？

先重新測試命令列 SSH，確認遠端登入服務及帳戶允許清單仍然正常；再查看 Server 是否能啟動。若重啟後每次都要手動修復，應記錄啟動後的服務狀態、磁碟掛載、代理環境和工作區權限，否則只刪除 Server 目錄通常不能解決根因。

按照以下條件選擇下一步：

• 若命令列 SSH 也失敗，回到網路、遠端登入、帳戶、主機指紋及金鑰層；在 VS Code 內重裝擴充功能不會修復底層 SSH。
• 若命令列能登入，但 ssh mac-dev 'echo ok' 失敗，檢查遠端 Shell、啟動腳本、權限及非互動式環境。
• 若 Server 下載失敗，檢查遠端出口、本機出口、代理及官方下載服務，不要先刪除遠端目錄。
• 若 Server 已下載但無法啟動，檢查可寫入空間、暫存目錄執行限制、殘留程序及遠端平台相容性。
• 若日誌出現 forwarding 被拒絕，檢查 SSH 服務的轉送政策及平台網路規則。
• 若連線成功但專案不能執行，將焦點移到遠端擴充功能、PATH、Git 認證、專案權限及 Apple Silicon 原生依賴。
• 若遠端 Mac 重啟後反覆失效，優先檢查節點是否能持續在線、帳戶權限是否穩定，以及重啟後 SSH 服務是否按預期恢復。

最後的驗收不是看狀態列是否顯示遠端主機，而是完成「開啟倉庫、啟動遠端終端機、執行專案命令、完成一次除錯或測試、重新連線後仍能恢復工作區」這五項操作。

如果目前使用的是辦公室內 Mac 或自行維護的 Mac mini，常見缺點是節點未必能長時間在線、重啟後服務狀態不透明，而且網路與防火牆故障需要由團隊自行處理。若使用一般 Linux 雲端主機，則不能直接滿足 Xcode、macOS 原生工具鏈或 Apple Silicon 相容性測試。

在完成本文的故障分層後，若現有節點仍缺少穩定管理權限、無法持續在線，或團隊難以重現重啟後的連線問題，可以先查看 JEXCLOUD 的遠端 Mac 使用方案，再按短期測試、CI 節點或持續開發週期選擇使用方式。這類方案不會取代所有本地硬體；但對需要臨時算力、遠端 macOS 工具鏈或可重複驗證的開發環境而言，通常比繼續維護一台不穩定的自有節點更容易建立清楚的驗收流程。

若已經確定需要按週期使用遠端 Mac，可進一步比較 香港交付方案 或 美國東部方案，並在下單前依本文清單確認 SSH 權限、VS Code Server 安裝、工作區擴充功能及重啟後復測條件。