故障排除
迁移中断
现象
迁移过程中外部存储断开、系统崩溃或应用被强制退出。
处理方法
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监控文件系统变化，通常会自动刷新 - 如果未自动刷新，可切换到其他标签再切换回来触发重新扫描
- 如果问题持续，检查日志中的扫描错误信息