故障排除
迁移中断
现象
迁移过程中外部存储断开、系统崩溃，或 AppPorts 被强制退出。
处理方法
AppPorts 内置自动恢复机制。重新启动 AppPorts 后，会按以下流程处理：
- 检测残留的迁移数据，例如外部副本已存在但本地符号链接尚未创建。
- 检查外部目录中的
.appports-link-metadata.plist。 - 如果
schemaVersion、managedBy、sourcePath、destinationPath和dataDirType完整匹配，自动接续迁移或恢复链接。 - 如果 metadata 不匹配或目标是真实目录冲突，停止自动处理并保留现有数据，等待用户手动确认。
通常不需要手动干预
AppPorts 会在下次启动时处理中断的迁移。如果自动恢复失败，可在数据目录列表中查看「待规范」或「待接回」状态，并手动执行对应操作。
外部存储离线
现象
外部存储被拔出或断开后，已迁移的应用无法启动，数据目录显示为红色错误状态。
处理方法
- 重新连接外部存储。
- AppPorts 的
FolderMonitor会自动检测到存储卷挂载，并触发重新扫描。 - 扫描完成后，应用和数据目录会恢复正常状态。
- 如果外置应用在 AppPorts 未运行时通过 App Store 更新了版本，重新扫描时会自动同步版本信息到本地 Stub Portal。
注意
外部存储离线期间，本地入口（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 应用迁移」。
- 手动迁移 App Store 应用。
- 应用更新后，再次迁移以覆盖外部副本。
macOS 15.1 及以上
如果 App Store 无法在外部存储上更新应用：
- 打开 App Store 设置。
- 开启「下载并安装大型 App 到独立存储盘」。
- 选择与 AppPorts 外部应用库相同的外部存储。
应用迁移后无法启动
排查步骤
- 检查外部存储连接：确认外部存储已连接且可访问。
- 检查应用状态徽章：
- 「孤立链接」：外部应用已丢失，需要手动解除链接。
- 「已损坏」：执行重签名。
- 检查锁定状态：如果应用被
uchg锁定，自更新程序可能无法运行。 - 查看日志：菜单栏 → 日志 → 在 Finder 中查看，搜索相关错误信息。
- 迁回本地：在外部应用库中选择「迁回本地」，确认问题是否由外部存储引起。
迁移时提示目标已存在
现象
迁移应用或数据目录时，AppPorts 提示目标位置已经存在，无法覆盖。
处理方法
- 应用迁移：如果外部目标不是「待迁出」对应的旧副本，也不是 AppPorts 能识别的旧入口或旧迁移残留，AppPorts 会停止迁移。请先在 Finder 中确认外部目标是否仍有价值，再决定手动备份、删除或改名。
- 数据目录迁移：如果外部目标目录没有匹配的 AppPorts metadata，AppPorts 不会按大小相近自动接管。请确认目录内容后手动处理，再重新迁移。
- 迁回本地：如果本地已有同名真实应用或不属于当前外部应用的符号链接，AppPorts 不会自动覆盖。请先确认本地项目来源。
数据目录显示异常
现象
数据目录列表显示不完整或状态不正确。
处理方法
- AppPorts 使用
FolderMonitor监控文件系统变化，通常会自动刷新。 - 快速切换应用时，旧扫描结果不会覆盖当前选中的应用；如果短时间内看到列表为空，等待当前扫描完成即可。
- 如果未自动刷新，可点击顶部工具栏的刷新按钮，或切换到其他标签页后再切回。
- 如果问题持续，请检查日志中的扫描错误信息。