VS Code Remote Agent Sessions 怎麼用？2026 遠端 Mac 部署

Remote Agent Sessions、Remote SSH、Dev Tunnel、VS Code Server 和傳統 CI Runner 不是同一個東西。

Remote Agent Sessions 是在 Agents window 中管理遠端 Agent 工作階段的入口。Remote SSH 是遠端開發連線方式。Dev Tunnel 是另一種遠端通道。VS Code Server 是遠端連線所需的伺服器元件，不等於 CI Runner。CI Runner 則是由持續整合系統調度的執行節點。

你需要將驗收拆成以下四層：

官方要求遠端主機保持開機並可連線。這是會話成立的前提，不是可靠性承諾。你可以在 Apple Remote Login 文件 中核對 macOS 的遠端登入設定，再查看 Remote SSH 官方配置說明 的客戶端與主機條件。

SSH 和 Dev Tunnel 不應只用「哪個比較快」來比較。真正的差別在於網路入口、身份管理、客戶端依賴和撤銷方式。

Dev Tunnel 必須啟用帳戶認證。匿名入口不應進入可接受方案。請以 Dev Tunnels 官方文件 核對目前的登入與管理方式，不要把社群貼文中的舊流程當成官方支援範圍。

第一步：建立最小連線驗收

先準備一個獨立帳戶、可回收的測試工作區和可讀取的測試倉庫。帳戶、主機名、路徑和倉庫均使用占位符，例如：

<REMOTE_USER>@<MAC_HOST>
<REMOTE_WORKSPACE>
<REPOSITORY_URL>

接著按這個順序取證：

• 在 macOS 開啟 Remote Login，確認允許的帳戶不是共享管理員帳戶。
• 從你的客戶端建立 SSH 連線，或以帳戶登入 Dev Tunnel。
• 在 Agents window 選擇遠端主機。
• 指定 <REMOTE_WORKSPACE>，確認 Agent 開啟的是正確目錄。
• 觀察連線失敗時顯示的是認證錯誤、主機離線、目錄不存在，還是權限不足。
• 關閉客戶端後重開，確認你能重新找到同一主機，而不是誤連另一個節點。

如果只能連到主機的 Shell，卻不能在 Agents window 選取正確目錄，先不要進行工具安裝。這通常是工作區或帳戶邊界問題，不是 Xcode 問題。

連線後，VS Code 會在遠端主機啟動執行 Agent 所需的命令列環境。你必須找出三個實際值：

• Agent 使用哪個 macOS 帳戶。
• 目前工作目錄是哪一個路徑。
• 使用哪個登入 Shell、PATH 和其他環境變數。

本地終端成功、Agent 會話失敗時，不要先重裝 VS Code。先比較兩邊的帳戶、pwd、echo "$SHELL"、command -v git 和 command -v xcodebuild 結果。常見差異包括登入 Shell 沒有載入初始化檔案、工具只存在於互動式 Shell、倉庫由另一個帳戶擁有，或 Agent 命令仍在等待人工批准。

你可以用以下最小閉環測試，避免一開始讓 Agent 操作敏感專案：

pwd
git status --short
printf '%s\n' "agent-check" > <TEST_FILE>
git diff -- <TEST_FILE>
rm -f <TEST_FILE>

通過標準不是「Agent 回覆成功」，而是你能在遠端主機觀察到：

• 讀取了預期檔案。
• 只修改了測試檔案。
• git diff 顯示修改內容。
• 測試檔案可被刪除。
• 沒有碰到工作區外的路徑。

Agent 的自動批准會放大遠端入口風險。請先閱讀 Agent 審批設定官方說明 和 Agent 安全說明，再決定哪些命令可自動執行。

經驗判斷： 對共享 Mac，預設拒絕比預設批准更容易追查。先批准讀取、版本控制和明確的測試命令；遇到安裝套件、刪除檔案、修改系統設定或讀取憑據時，要求人工確認。

「遠端 Agent 可以執行 xcodebuild」只是一個命令層結果。它不代表完整的 iOS 開發或發布鏈路已經成立。

先在與 Agent 相同的帳戶、相同工作目錄執行：

xcode-select -p
xcodebuild -version
xcodebuild -list -project <PROJECT_PATH>
xcodebuild -showBuildSettings -project <PROJECT_PATH>

Apple 的 Xcode 命令列工具參考 可用來核對命令用途；建置設定則應對照 Xcode Build Settings Reference。不要只看 xcodebuild -version 有輸出，就宣布節點可以建置所有專案。

先完成無圖形介面的建置或檢查，再處理 Simulator。涉及簽名憑證、Provisioning Profile、Team ID、真機或生產發布時，必須轉入獨立驗收流程。這些能力不是 Remote Agent Sessions 的通用官方承諾，而是需要你在真實 Mac 專案上復測的工程判斷。

第二步：把失敗證據留在同一層

遇到錯誤時，記錄以下內容：

• Agent 使用的帳戶與工作目錄。
• xcode-select -p 和 command -v xcodebuild 輸出。
• 專案 scheme、SDK、建置設定和錯誤碼。
• 是否需要圖形工作階段。
• 是否觸發憑據或工具批准。
• 失敗前後的 Git 工作區狀態。

若命令在本地終端成功、在 Agent 中失敗，優先查環境變數、登入 Shell、目錄權限和審批狀態。若命令在兩邊都失敗，才把問題轉向 Xcode 版本、專案設定或依賴。

個人節點和共享節點的風險不同。個人節點可以使用單一工作區，但仍不應讓 Agent 直接讀取整個家目錄。共享節點則要把帳戶、倉庫、工作區和憑據分開。

不要把簽名證書、發布令牌、App Store Connect 憑據或長期 SSH 私鑰直接交給 Agent。若工作確實需要其中一項，先定義：

• 哪個命令需要它。
• 允許它存在多久。
• 哪個帳戶可以讀取。
• 如何在失敗時撤銷。
• 哪一筆變更記錄可以追溯這次放權。

對共享節點，Git worktree 可以減少不同分支互相覆寫的機會，但它不是安全邊界。檔案權限、macOS 帳戶和憑據存放位置仍要另外設計。

不要用「客戶端還開著」判斷節點可長期運作。你需要刻意中斷，再觀察 Agent、工作區和任務狀態。

測試時依次記錄：

• 關閉本地 VS Code，稍後重新開啟。
• 暫停客戶端網路，再恢復連線。
• 停止 Dev Tunnel，再重新進行帳戶認證。
• 重啟遠端 Mac。
• 重啟後確認 Remote Login、必要服務和工作區仍可用。
• 用新會話重新執行唯讀命令和最小 Xcode 檢查。
• 確認未提交修改、產物和日誌沒有被誤刪。

官方資料只確認遠端主機需要在線且可達，並不替你的 Xcode 任務、簽名流程或恢復腳本背書。因此，恢復結果只能標記為你的隔離遠端 Mac 實測；沒有實測，就不要寫成「支援自動恢復」。

第三步：作出上線分級

如果你需要的是可回收的隔離節點，而不是立刻購買硬體，可以先查看 CALMVPS 的遠端 Mac 方案，再以短週期測試實際工作區和 Xcode 命令。需要比較租用週期與方案時，可參考 CALMVPS 方案與價格頁。選擇節點時，地區、存取方式、重啟安排和帳戶邊界要與測試記錄一起評估，不能只看規格名稱。

見文末折疊問答。這些問題分別涵蓋 macOS 連線資格、xcodebuild 執行、SSH 與 Dev Tunnel 選擇、重啟後恢復，以及共享 Mac 的倉庫和憑據隔離。任何一題沒有可觀察證據，都應保留在試驗層，不要直接推進生產。

VS Code Remote Agent Sessions 遠端 Mac 的正確用法，不是把「連線成功」當成部署完成，而是逐層驗收：主機可達、工作區正確、Agent 命令可控、Xcode 工具鏈可用，最後再測試中斷和重啟。預覽功能可以提高試驗速度，但不能替你承擔簽名、憑據和生產發布風險。

如果目前方案是 Windows 或 Linux 主機加上臨時轉發，你可能會遇到 macOS 工具鏈不完整、圖形工作階段難以維持、重啟後環境不一致，以及簽名憑據分散在不同機器等問題。虛擬化方案也可能受限於 Apple 工具鏈、硬體存取和授權邊界。需要真實 macOS 節點時，使用 CALMVPS 的遠端 Mac 租用建立隔離試驗環境，通常比先購置一台只為短期驗證的 Mac 更容易回收成本；完成會話、Xcode 命令與重啟驗收後，再決定續用、調整配置或停止租用。

若要先比較可用入口與交付方式，也可以從 CALMVPS 遠端 Mac 入口開始，並把本文的檢查結果帶入你的正式上線審查。

最後更新於 2026 年 9 月 13 日；預覽狀態、連線方式與安全提示核實自 VS Code 官方文件，Remote Login 設定核實自 Apple 官方文件。Xcode 執行與恢復能力仍須以你的隔離遠端 Mac 實測為準。