官方文件已確認，VS Code Remote - SSH 連線時會在遠端主機安裝並執行 VS Code Server；因此「終端 SSH 已成功，但 VS Code 一直停在連線或安裝伺服器階段」時，不應直接重試或清除快取。先用系統終端驗證基礎 SSH，再查看 Remote - SSH 詳細日誌，依序定位到認證、連接埠轉發、VS Code Server、遠端擴充功能主機或節點資源層；若伺服器元件重啟後仍反覆失敗，應修復節點基線或更換遠端 Mac。
你適合閱讀這篇文章，如果：
你主要使用 Windows 或 Linux，卻需要透過 VS Code 使用 macOS 工具鏈；或你在本地 Mac 上維護共享遠端開發節點、CI 工作站。若你負責驗收雲端 Mac 租賃服務，也可以用文中的復測時間線判斷問題究竟在客戶端，還是在節點本身。
SECTION 01 開始前的故障時間線
不要把「可以 Ping 到」或「TCP 連接埠有回應」視為 SSH 已可登入。macOS 必須開啟 Remote Login，並允許指定帳戶接受 SSH 或 SFTP 存取；可先依照 Apple 的 Remote Login 官方指南 核對系統設定。
建議你按以下里程碑保存輸出，避免每次修改後失去原始證據：
- 里程碑 A：基礎通道
在本地終端以與 VS Code 相同的主機別名、帳戶和金鑰測試 SSH。記錄成功登入、密碼提示、主機指紋提示或具體錯誤，而不是只記錄「連不上」。 - 里程碑 B：編輯器介入前
在 VS Code 開啟 Remote - SSH 輸出面板，將記錄層級調到詳細程度，保存實際呼叫的 SSH 客戶端、設定檔路徑、認證流程和遠端指令。 - 里程碑 C：遠端元件
確認是否已完成認證、是否建立轉發通道，以及 VS Code Server 是否下載、解壓和啟動。 - 里程碑 D：功能閉環
連線後不要只看 Explorer 是否出現；必須開啟同一個工作區、執行遠端終端、完成 Git 操作與實際建置，再進行斷線和重啟復測。
這條時間線能把「網路可達」「SSH 可登入」「轉發可用」「伺服器元件可運作」分開。官方的 Remote - SSH 使用說明 也將遠端主機上的 VS Code Server 視為連線流程的一部分，而不是普通檔案傳輸。
SECTION 02 終端 SSH 與 VS Code 的分層證據
兩者同時失敗
先在遠端 Mac 的本地控制台或備用管理通道確認 Remote Login 狀態，再核對主機地址、指定帳戶、允許存取的使用者和 SSH 服務是否正在運作。修改 Remote Login 或 SSH 服務前，必須保留備用登入方式；如果你只有一條遠端通道，重啟服務可能立即令自己失聯。
本地終端可使用占位符測試：
ssh -vvv <user>@<remote-mac>
-vvv 的價值在於提供認證方法、主機指紋、密鑰選擇與通道協商證據。請不要在文章、工單或截圖中公開私鑰內容；需要分享時只保留錯誤行和已遮蔽的路徑。
若終端與 VS Code 同時失敗，優先檢查：
<user>是否是遠端 Mac 上實際允許登入的帳戶；- 主機名稱是否解析到正確節點，而非已被重新分配的地址；
- 本地
~/.ssh/config是否包含不同的HostName、Port或IdentityFile； - macOS 的 Remote Login 是否被關閉，或帳戶權限已變更；
- 備用管理通道能否觀察磁碟、記憶體與 SSH 服務狀態。
終端成功、Remote - SSH 失敗
這是最容易誤判的分支。終端成功，僅能證明某一個 SSH 客戶端以某一組參數登入成功；VS Code 可能調用了另一個 SSH 執行檔、另一份設定檔，或沒有讀取你以為會使用的金鑰。
在 Remote - SSH 輸出中，比對以下項目：
| 檢查項目 | 終端測試 | VS Code 應確認的證據 | 低風險處理 |
|---|---|---|---|
| SSH 客戶端 | ssh -vvv 顯示的執行檔 |
日誌中的實際呼叫路徑 | 統一本地 SSH 客戶端與設定 |
| 帳戶與主機 | <user>@<remote-mac> |
連線命令與 Host 別名展開結果 | 修正 Host、User、HostName |
| 金鑰認證 | IdentityFile 與代理狀態 |
VS Code 日誌中的金鑰選擇 | 只使用受控金鑰，不共享私鑰 |
| 互動提示 | 密碼、金鑰口令、指紋 | 是否停在等待輸入 | 回到終端完成提示驗證 |
| 後續通道 | 登入後可否執行命令 | 是否出現轉發拒絕 | 進入 TCP 或 Socket 轉發分支 |
如果日誌停在密碼、金鑰口令或主機指紋提示，問題不是 VS Code Server。若日誌顯示另一個 IdentityFile，應先統一客戶端設定，不要以關閉主機校驗或複製私鑰的方式繞過認證。
SECTION 03 轉發與 VS Code Server 故障
連接埠轉發被拒絕
認證完成後，若日誌出現 administratively prohibited、通道建立失敗或本地連接埠已被使用，請先把它與登入故障分開。Remote - SSH 需要額外的轉發通道；普通 SSH 能進入 Shell，不代表這條通道也得到主機策略允許。
依照 VS Code 官方的 TCP forwarding 排障說明，檢查遠端 SSH 設定是否限制 TCP 轉發；若環境使用 Unix Socket，也要按 OpenSSH sshd_config 參數手冊核對相關策略。修改 AllowTcpForwarding 或 AllowStreamLocalForwarding 可能影響其他使用者、既有 CI 連線和安全邊界，因此要先保存目前設定，並安排可回復的備用入口。
每次調整後，都要依次重測普通 SSH、VS Code Remote SSH 和既有 CI 工作。只修好編輯器而破壞自動化建置，不算完成修復。
Installing VS Code Server 停滯
停在 Installing VS Code Server 時，先不要立即執行清理。將故障分成四類：
- 遠端帳戶無法存取下載來源；
- VS Code Server 目錄不可寫、磁碟不足或檔案不完整；
- Shell 啟動腳本輸出了額外文字，干擾遠端指令通訊；
- 元件已下載，但進程因權限、資源或環境變數而無法啟動。
先從 Remote - SSH 輸出確認目前停在哪一個階段，再登入遠端帳戶檢查主目錄與伺服器目錄狀態。不要把網路延遲直接當成下載失敗，也不要把下載失敗直接歸因於 VS Code 版本。
只有在證據明確指向遠端伺服器檔案損壞時，才使用官方 Remote - SSH 伺服器清理方法。清理前要提醒所有使用該帳戶的工作階段會被終止，並保存目前日誌、工作目錄狀態及可重現步驟。清理後重新連線，若仍在相同階段失敗，下一個方向應是節點基線、帳戶權限或資源壓力，而不是重複清理。
提醒： 修改 SSH 服務、重置主機指紋或刪除 VS Code Server 目錄，都可能令現有通道失效。沒有備用控制台或其他管理入口時，先不要在唯一的遠端工作階段中執行這些動作。
已連線但擴充功能不可用
成功開啟工作區後，問題可能轉移到 Remote Extension Host 或專案進程。你要分別觀察：
- SSH 工作階段是否斷開；
- Remote Extension Host 是否停止或反覆重啟；
- 遠端 Mac 的記憶體、磁碟與 CPU 是否出現壓力；
- 代理環境變數是否只在 VS Code 啟動時存在；
- 擴充功能是否依賴特定的 macOS 原生元件或架構。
多重連線時，ControlMaster、連線保活和代理變數只能在符合條件時使用。若是動態分配節點，每次連線可能落到不同主機，先參考 VS Code 動態節點與連線復用說明，確認主機身份、工作目錄和 SSH 連線復用是否一致；不要用增加保活參數掩蓋節點不穩定。
SECTION 04 重啟後的驗收分支
完成修正後，使用同一個 <repo-path> 做一次完整驗收：
- 首次連線並開啟工作區；
- 在 Remote Terminal 執行環境檢查；
- 讀取與修改一個測試檔案；
- 執行 Git 狀態、拉取或分支操作；
- 執行實際的建置或測試命令；
- 手動中斷本地客戶端，再重新連線；
- 重啟遠端 Mac，等待系統可管理後重新測試 Remote Login、VS Code Server 和專案命令。
接著使用以下決策條件：
- 若終端 SSH、Remote - SSH、工作區操作和建置全部成功，且重啟後可以恢復，則保留目前節點，將設定與復測證據寫入維運文件。
- 若普通 SSH 穩定，但 VS Code Server 只在清理後短暫恢復，則檢查磁碟、帳戶目錄、啟動腳本與節點資源；不要把清快取當作長期修復。
- 若基礎 SSH 成功、轉發穩定，但遠端擴充功能因原生依賴失敗，則單獨驗證該擴充功能的 macOS 與 Apple Silicon 要求，再決定更換工具或調整環境。
- 若遠端 Mac 重啟後 Remote Login、帳戶環境或 VS Code Server 無法恢復，則選擇重建節點基線或更換節點；只有在故障證據指向客戶端設定時，才繼續修改本地 VS Code。
- 若你無法取得日誌、節點資源狀態或備用管理入口，則先補齊可觀測性，再驗收開發體驗，否則無法區分偶發斷線與節點故障。
SECTION 05 FAQ
以上分層也回答了幾個最常見的搜尋情境，但請特別記住：基礎 SSH、轉發通道、VS Code Server、Remote Extension Host 和專案進程是不同故障面。修復其中一層後，必須回到同一個工作區完成重測，才有資格判定連線已恢復。
如果你需要一台可長時間保留開發環境、具備管理權限並能進行重啟驗收的遠端 Mac，先查看 VPSNIX 的遠端 Mac 方案與租賃資訊，再按你的工作區、CI 流程和備援入口逐項驗證。現有方案若只是臨時共用節點，常見缺點是 SSH 設定不可控、重啟後環境不一定能恢復，以及沒有足夠的日誌或備用控制台；這些問題會讓每次 VS Code 失敗都變成重複猜測。若你打算把節點納入團隊流程，可再透過 VPSNIX 說明中心確認交付、管理與恢復方式，讓遠端 Mac 租賃不只解決「能否連上」，也能通過實際建置與重啟驗收。
SECTION 06 常見問題 FAQ
為什麼終端 SSH 可以登入，但 VS Code Remote SSH 仍然連不上？
終端 SSH 成功只代表基本登入通道可用，VS Code Remote SSH 還需要正確讀取同一份設定、完成認證後建立轉發通道，並在遠端啟動 VS Code Server。請比較實際使用的 SSH 客戶端、使用者名稱、IdentityFile、主機指紋與 Remote - SSH 詳細日誌，不要只測試主機是否可達。
VS Code Server failed to start 在 Mac 上應該怎樣處理？
先從 Remote - SSH 輸出及遠端登入終端確認是啟動指令失敗、Shell 啟動腳本干擾、目錄檔案不完整，還是節點資源不足。只有在證據指向伺服器安裝損壞時，才使用官方提供的清理或重裝動作，並先確認這會終止該帳戶現有的遠端工作階段。
Remote SSH 一直停在 Installing VS Code Server，應從哪裡開始？
先分開檢查遠端 Mac 是否能連到必要的下載來源、帳戶目錄是否可寫，以及登入 Shell 是否輸出了額外文字。若遠端節點無法連外，可按官方排障文件採用本地取得後傳送的方式；若檔案不完整，再考慮清理伺服器並重新建立連線。
遠端 Mac 重啟後 VS Code Remote SSH 無法連線，怎樣判斷要修復還是換節點？
先用系統終端確認 macOS Remote Login 是否仍在運作，再檢查同一帳戶的 SSH 認證、工作目錄與 VS Code Server。若基礎 SSH 穩定但伺服器元件在每次重啟後都失敗，或磁碟與帳戶環境無法恢復，就應重建基線或更換節點，而不是反覆刪除快取。