在遠端 Mac 上驗收 macOS App 的登入項目

團隊開發的 macOS 選單列 App 需要在使用者登入後啟動。你在遠端 Mac 上開啟「登入時啟動」，介面顯示已啟用；中斷遠端桌面連線後再連回去，卻發現 App 根本沒有退出。這無法證明登入項目有效。驗收時必須分別記錄註冊、使用者核准、真正重新登入後的啟動，尤其不能把遠端用戶端斷線當成 macOS 登出。

先確定測試對象與範圍

本文測試的是透過 SMAppService.mainApp 註冊的主 App 登入項目，不是背景輔助程式或系統啟動服務。目標 App 必須支援 macOS 13 或更新版本，並在 App 自身的程序中呼叫註冊介面；單獨執行一段命令列 Swift 腳本，無法代替它完成同一項註冊。

準備一個獨立的標準使用者作為測試帳號，事先確認能重新登入該帳號的圖形桌面。不要直接用正在執行建置工作的帳號測試：登出會結束互動工作階段，也可能中斷依賴該工作階段的程序。先儲存工作、記下重新連線的方法，再開始測試。

「已註冊」、「已獲核准」、「登入後已啟動」是三個不同的結論。每個結論都需要相應證據，不能從前一個狀態推斷下一個狀態。

檢查安裝後的 App

使用預計交付的 App 套件測試，不要只在 Xcode 中按下執行。將以下路徑換成實際安裝位置：

APP="/Applications/ExampleApp.app"
test -d "$APP" || { echo "App bundle not found"; exit 1; }
/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' \
  "$APP/Contents/Info.plist"
codesign --verify --deep --strict --verbose=2 "$APP"

記錄輸出的 bundle identifier，並確認它與這次的建置目標一致。若 codesign 驗證失敗，應先處理 App 套件，不要把無法正常啟動誤判為登入項目故障。簽章驗證通過，也不代表已完成使用者核准或登入後啟動測試。

在 App 內處理註冊狀態

將註冊動作連接到 App 設定中的明確開關，不要在每次啟動時無條件呼叫。以下程式碼應放在 macOS App 目標內；呼叫端應依照傳回的狀態顯示相應提示：

import ServiceManagement

@MainActor
func enableLaunchAtLogin() throws -> SMAppService.Status {
    let service = SMAppService.mainApp
    if service.status == .notRegistered {
        try service.register()
    }
    return service.status
}

只有傳回 .enabled，才能在介面上顯示為已啟用。若傳回 .requiresApproval，應提示使用者前往系統設定檢查，不要顯示為操作失敗，也不要暗中反覆註冊。例外狀況也應交由介面處理。關閉開關時，須在 App 內呼叫 try SMAppService.mainApp.unregister()，接著重新讀取狀態，不能只改變開關外觀。

核對使用者核准狀態

在同一個測試帳號下開啟系統設定，查看登入項目相關頁面，確認 App 是否列出、是否需要手動允許。設定項目的名稱可能隨 macOS 版本而變，應以目前系統介面為準。核准後返回 App，再次讀取 SMAppService.mainApp.status；不要只因系統設定中出現 App 名稱，就記下「自動啟動已通過」。

進行一次真正的重新登入

先正常退出 App，記錄此時它並未執行。接著使用 macOS 選單明確登出測試帳號，再重新登入該帳號的圖形桌面。觀察 App 視窗、選單列圖示，或 App 本身可供核對的執行狀態；測試前先約定哪一項算是「啟動成功」，避免將啟動後立即當機誤判為通過。

最後一項須在 App 內停用登入項目後再測試。若 App 還會透過其他機制啟動，應先找出那些機制，不能只憑程序仍在執行就否定停用結果。測試結束後再視需要重新啟用，並確認開關狀態。

排除遠端工作階段造成的假象

關閉遠端桌面用戶端、網路短暫中斷，或只是鎖定螢幕，都不一定會結束 macOS 使用者工作階段。重新連線後看到原本的視窗，通常只能證明工作階段仍在，不能證明登入項目曾觸發。透過 SSH 啟動 App 也不等於測試圖形介面登入；SSH shell 與桌面工作階段的環境不同。

若註冊狀態正確，但登入後看不到 App，請依序檢查：是否登入了註冊時使用的同一個帳號、測試的是否為安裝套件而非另一份建置副本、系統設定是否仍要求核准，以及 App 是否啟動後立即退出。若 App 有啟動日誌，請記錄事件時間與這次登入的時間，以區分「未啟動」和「啟動後失敗」；不要在日誌中寫入存取憑證。

留下驗收結果供下次建置使用

保留一份簡短紀錄：App 版本、bundle identifier、macOS 版本、測試帳號、註冊前後狀態、核准操作、重新登入結果，以及停用後的複測結果。每次更新 App 套件後，至少重新核對已安裝 App 的身分資訊與重新登入結果；若變更了登入項目的實作，則須重新測試註冊與停用兩條路徑。

這套流程的價值，不是證明某台電腦「永遠都會自動啟動」App，而是讓特定建置的行為可以重現、方便排查。只要將圖形介面登入與遠端連線區分開來，通常就能把登入項目問題縮小到 App 套件、使用者核准或 App 啟動本身。

常見問題