故障排除
遷移中斷
現象
遷移過程中外部存儲斷開、系統崩潰或應用被強制退出。
處理方法
AppPorts 內置自動恢復機制。重新啓動 AppPorts 後：
- 檢測到殘留的遷移數據（外部副本存在但本地符號鏈接未創建）
- 自動比較本地與外部目錄大小（90% 閾值）
- 若數據完整，自動完成遷移（刪除本地原始目錄，創建符號鏈接）
- 若數據不完整，清理殘留的外部副本，恢復原始狀態
💡 不需要手動干預
AppPorts 的自動恢復機制會在下次啓動時處理中斷的遷移。如果自動恢復失敗，可在數據目錄列表中看到「待規範」或「待接回」狀態，手動執行對應操作即可。
外部存儲離線
現象
外部存儲拔掉或斷開後，已遷移的應用無法啓動，數據目錄顯示爲紅色錯誤狀態。
處理方法
- 重新連接外部存儲
- AppPorts 的
FolderMonitor會自動檢測到存儲卷掛載，觸發重新掃描 - 應用和數據目錄恢復正常使用
⚠️ 注意
外部存儲離線期間，本地入口（Stub Portal）調用 open 命令會失敗，應用無法啓動但不會崩潰。數據目錄的符號鏈接指向無效路徑，關聯應用可能讀取不到數據。
簽名恢復失敗
現象
嘗試恢復原始簽名時失敗，或恢復後應用仍提示「已損壞」。
可能原因與處理
| 原因 | 處理方法 |
|---|---|
| 備份文件不存在 | 無法恢復原始簽名，可執行 Ad-hoc 重簽名替代 |
| 原始開發者證書不在本機鑰匙串中 | AppPorts 會自動回退爲 Ad-hoc 簽名，應用可啓動但 Keychain 訪問可能異常 |
| Mac App Store 應用（SIP 保護） | 無法重簽名，SIP 阻止對系統應用簽名的任何修改 |
| 應用目錄爲 root 所有 | AppPorts 會嘗試通過管理員權限修改所有者，需在彈窗中授權 |
| Contents 符號鏈接目標已丟失 | 無法簽名，需先恢復外部數據或還原應用 |
詳細機制請參閱重簽名與崩潰防護。
App Store 應用無法遷移到外置硬盤
macOS 15.1 以下
macOS 15.1 之前版本不支持 App Store 應用安裝到外置硬盤。需：
- 在 AppPorts 設置中開啓「App Store 應用遷移」
- 遷移後應用更新需手動二次遷移以覆蓋
macOS 15.1 及以上
如果 App Store 無法在外置硬盤上更新應用：
- 打開 AppStore 設置
- 開啓「下載並安裝大型 App 到獨立存儲盤」
- 選擇與 AppPorts 中外部存儲庫相同的外置存儲
應用遷移後無法啓動
排查步驟
- 檢查外部存儲連接：確認外部存儲已連接且可訪問
- 檢查應用狀態徽章：
- 「孤立鏈接」→ 外部應用已丟失，需手動解除鏈接
- 「已損壞」→ 執行重簽名
- 檢查鎖定狀態：如果應用被鎖定（uchg），自更新程序可能無法運行
- 查看日誌：菜單欄 → 日誌 → 在 Finder 中查看，搜索相關錯誤信息
- 遷回本地：在外部應用庫中選擇「遷回本地」，確認是否爲外部存儲問題
數據目錄顯示異常
現象
數據目錄列表顯示不完整或狀態不正確。
處理方法
- AppPorts 使用
FolderMonitor監控文件系統變化，通常會自動刷新 - 如果未自動刷新，可切換到其他標籤再切換回來觸發重新掃描
- 如果問題持續，檢查日誌中的掃描錯誤信息