AppPorts Files

AppPorts v1.9.2 Build 40 更新说明 （in English） · 直链下载 · 赞助

总结

这次更新修的是「卡住」：应用明明迁到了外盘，却迁不回来。 如果你在 1.9.0 里迁移过会在应用内自动更新的应用（Chrome、VS Code、微信这类），升级到 1.9.1 后可能发现它们无法迁回本地，只看到「无法完整保留此项目的内容或权限」或「路径对应的对象或磁盘已改变」。原因是 1.9.0 给外盘副本加的锁定标记没有被记录下来，1.9.1 认不出来，于是在复制之前就停下了。

现在 AppPorts 不再纠结「这把锁是谁加的」。位置变更时统一清除锁定标记、保留其它所有权限设置，然后正常迁移；来源不明的锁照样保留。同时，那些永远无法完成的旧记录不再反复重试，也不会再变成需要你判断的弹窗——AppPorts 会把这张记录移入归档目录，不动任何应用或数据。

另外两类问题也一并解决：拷贝时遇到 macOS 自动压缩的文件（App Store 装的、长期没运行的可执行文件）会复制失败，现在能正确处理；迁到不保存文件所有者的磁盘（exFAT、关闭所有权校验的 HFS+）时，AppPorts 会在确认框里提前说明。

升级提示

这次更新不需要你做任何准备工作。 已经迁移的应用留在原处即可，插盘后的「接回」、需要时的「还原」都按原记录进行。升级不会改动应用签名，也不会要求你重新搬运已经迁好的内容。

如果你之前卡在「无法迁回本地」，更新后重试一次即可。 之前失败时会留下一张未完成的记录，现在它能被正常处理：能继续的继续；不能继续的，AppPorts 把记录移入归档目录后放行。归档只动这张记录，应用和外盘副本都留在原处，不会多出一份副本。你不需要手动删除 ~/Library/Application Support/AppPorts 下的任何文件。

迁移普通应用不需要 APFS。 但如果你要迁移容器数据（挂载迁移），仍然需要未加密的 APFS 外置盘和完全磁盘访问权限。

目标盘不保存文件所有者时，个别应用可能拒绝工作。 详见下方「新功能」中的说明；如果你遇到这类提示，把数据留在本机或换用 APFS 磁盘。

修复

从外盘迁回本地失败的问题 — 1.9.0 迁移自更新应用时，会用不可变标记锁住外盘副本，但不记录锁了哪些对象；1.9.1 改为只撤销自己记录过的锁，于是这些锁成了「来历不明」的锁，迁回时在复制前就被拒绝。现在位置变更统一清除整棵树的不可变标记，无论它呈现为整树锁定、只锁根目录还是只锁部分子项——这些形态都出自同一次锁定，只是之后被应用更新破坏得不完整。只清除不可变标记，其它标志位仍然保留，遇到无法保留的标志位仍会拒绝并保留原件。相关反馈：#77。

卡住的应用记录不再无限重试 — 一个缺少校验清单、或外盘副本已被替换的旧记录，永远无法完成，却会一直占用该路径，并让后台维护在每次启动时重复失败。现在维护流程判断出「重试不可能改变结果」后，会把记录归档到 app-transfers/archived/ 并释放路径。归档只移动记录本身，应用、外盘副本、临时目录全部留在原处。

记录清理顺序修正 — 之前删除转移记录时先删校验清单、再删记录，一旦中断就会留下永远无法验证、也无法自行完成的记录，永久占用路径。现在先删记录、再删清单。

macOS 自动压缩的文件导致整个应用无法迁移 — 系统会对部分文件做透明压缩（UF_COMPRESSED，App Store 安装的可执行文件、长期未运行的二进制）。原来的复制逻辑按磁盘物理块读取，对压缩文件会读出错内容、校验失败，进而拒绝整个应用——实测一个 572 MB 的应用仅因其中一个 GPU 辅助程序被压缩就无法迁移。现在对这类文件改用普通顺序读取（系统会解码），复制结果是文件的真实内容。实测校验一致、副本可执行。相关反馈：#77。

替换目标时的初始状态记录 — 替换已存在的应用前，需要先记录其初始状态才能安全回滚。这个记录原来在解锁之后才写，失败时会留下一条永远无法推进的记录。现在改为先解锁、再记录、然后才开始移动内容，任一步失败都会在改动任何一方之前停止。

新功能

迁移前提示目标盘不保存文件所有者 — exFAT 和 FAT32 没有文件所有者字段，关闭所有权校验的 HFS+ 会把新文件记成占位用户。普通读写不受影响，但少数用管理员权限核对归属的应用（例如 clash-verge 带特权后台服务）会拒绝工作并报错 1012。这类应用通常建议你执行 chown 修复，但这条命令在这类卷上会被系统静默丢弃，怎么试都无效。现在迁移数据目录和自选文件夹时，确认框会提前说明目标盘的这一情况，不阻止继续操作。APFS 不在提示范围——即使在忽略所有权的挂载下，APFS 仍保存真实归属。相关反馈：#78。

界面与行为变化

移除了「未完成的应用操作」面板 — 1.9.1 的开发过程中曾计划让用户手动处理卡住的迁移记录（重试 / 取消 / 结束记录）。但这个面板实际把「已迁移完成、只剩清理旧副本」这种内部收尾也列了出来，而这类记录既不能取消、也不该结束——界面上只会剩下按不动的按钮。卡住的记录只有两种结局：继续完成，或把记录移入归档目录后放行；两种都不需要只有用户才知道的信息，也都不涉及删除你的应用或数据。现在这些全部由 AppPorts 自己处理，界面上没有任何相关入口。

迁回后不再保留外盘锁定 — 应用回到本地后不再加锁定标记，因为没有需要保护的外盘副本。应用留在外盘时（迁移、索引排除）仍会保留锁定保护，且这次带有记录，以后能被正确识别。

已知限制

• 如果你在 1.9.0 时期手动解锁过某个应用的部分文件，那些文件仍然能正常迁回；但如果你自己在访达里锁定了外盘应用，迁回时这个锁也会被清除。AppPorts 无法区分两者，需要在迁回后重新设置。
• 目标盘不保存文件所有者的提示目前只覆盖数据目录和自选文件夹迁移；应用本体迁移不写应用数据，不在此范围。

⚠️ “AppPorts”已损坏，无法打开

如果从 AppPorts 官方发布渠道下载后遇到此提示，可能与 macOS 对未进行 Developer ID 签名和公证的应用进行隔离有关。

确认下载来源后，将 AppPorts 拖入「应用程序」文件夹，再在终端运行：

:::shell
xattr -rd com.apple.quarantine /Applications/AppPorts.app

迁移使用提示

• 升级后建议先试一次之前失败的应用迁回。
• 如果某个应用仍然迁不回来，把错误信息连同「帮助 → 日志 → 导出诊断包」发到 GitHub Issues，诊断包已自动脱敏。
• 迁移后的目录请继续按原来的习惯使用：先连接外置盘，拔盘前先退出应用并正常推出，重要数据另行备份。

English Release Notes

Summary

This update fixes "stuck": apps that moved out but could not move back. If you migrated self-updating apps (Chrome, VS Code, WeChat and similar) with 1.9.0, upgrading to 1.9.1 could leave them unable to return to local storage, showing only "could not fully preserve this item's contents or permissions" or "the object or disk at this path has changed." The cause was that 1.9.0 locked the external copies without recording which objects it had locked, so 1.9.1 could not recognize those locks and stopped before copying anything.

AppPorts no longer tries to decide who set a lock. A location change now clears the immutable flag across the whole tree, leaves every other permission setting alone, and proceeds; locks it cannot attribute are still preserved. Separately, journals that can never complete are no longer retried forever, and they no longer become a dialog asking you to decide — AppPorts moves that one record into an archive folder and leaves every app and copy untouched.

Two other classes of failure are fixed as well: copies no longer break on files macOS compresses transparently (App Store installs, long-idle executables), and migrating to a disk that does not record file owners (exFAT, or HFS+ with ownership checks off) now warns you up front.

Upgrade Notes

This update asks you to prepare nothing. Already-migrated apps can stay where they are; reconnecting after you plug the drive in and restoring when you need to both follow existing records. The upgrade does not change app signatures and does not ask you to move anything again.

If you were stuck on "cannot move back to local", simply retry after updating. Earlier failures left an unfinished record behind; it is now handled properly: what can continue does, and what cannot has its record moved into an archive folder so the path is free again. Archiving touches that record only — your app and the external copy stay where they are, and no extra copy is made. You do not need to delete anything under ~/Library/Application Support/AppPorts by hand.

Moving ordinary apps still needs no APFS. Container data migration (mount migration) still requires an unencrypted APFS external drive and Full Disk Access.

Some apps may refuse to work when the target disk does not record file owners. See New Features below; if you hit such a message, keep that data local or use an APFS disk.

Fixes

Restoring an app from external storage failed — When 1.9.0 migrated a self-updating app it locked the external copy with the immutable flag but recorded nothing about which objects it locked. 1.9.1 only revokes locks it recorded itself, so those bits became unattributable and the restore was refused before copying. A location change now clears the immutable flag over the whole tree, whether it presents as a fully locked tree, a locked root only, or a few locked children — all of those come from the same lock, just left uneven by a later app update. Only the immutable flag is cleared; other flags survive, and an unsupported flag still refuses the operation and keeps the original. Related report: #77.

Stuck app records are no longer retried forever — A record missing its verification manifest, or whose external object was replaced, can never complete, yet it kept its paths blocked and made background maintenance fail again on every launch. Maintenance now recognizes "retrying cannot change this" and archives the record to app-transfers/archived/, freeing the path. Archiving moves only the record; the app, external copy and staging directories stay where they are.

Record cleanup order corrected — Removing a transfer record used to delete its verification manifests before the record itself. An interruption then left a record that could never be verified or completed again, permanently occupying its path. The record is now removed first.

Files macOS compresses transparently broke whole-app migration — The system compresses some files transparently (UF_COMPRESSED: App Store executables, long-idle binaries). The copier read physical extents, which for a compressed file returns the compressed stream, so verification failed and the whole app was refused — a 572 MB app failed over a single compressed GPU helper. Such files now take the ordinary sequential path (the kernel decodes them), so the copy holds the file's real contents. Verified against a real app: hashes match and the copy stays executable. Related report: #77.

Replaced-target baseline captured before anything moves — Before replacing an existing app, its initial state must be recorded for safe rollback. That record used to be written after the flags were suspended, and a failure left a record that could never advance. Now the flags are suspended, the baseline is recorded, and only then does content move; a failure at any step stops before changing either side.

New Features

A warning when the target disk does not record file owners — exFAT and FAT32 have no ownership field, and HFS+ with ownership checks off writes new files as a placeholder user. Ordinary reads and writes are unaffected, but a few apps that check ownership as an administrator (clash-verge with its privileged service, for example) refuse to work and report error 1012. Those apps usually suggest a chown fix, but on such volumes the system silently drops the command, so nothing ever works. Migrating a data directory or custom folder now explains the target's situation in the confirmation dialog without blocking. APFS is out of scope because it keeps the real owner even when mounted with ownership ignored. Related report: #78.

Interface and Behaviour Changes

The "unfinished app operations" panel is gone — During 1.9.1 development there was a plan to let users handle stuck migration records by hand (retry / cancel / end record). In practice the panel also listed committed transfers whose only remaining work was deleting an old copy, and such a record can neither be cancelled nor safely ended — the panel ended up offering buttons that could only fail. A stuck record has two possible outcomes: finish, or have its record moved into an archive folder so the path is released. Neither needs information only the user has, and neither deletes your app or data. AppPorts now handles both itself, and there is no entry point in the UI.

Restored apps carry no external lock — An app that is back on local storage is no longer locked, because there is no external copy to protect. While an app stays external (migration, search exclusion) the lock is still applied, and now it is recorded so it can be recognized later.

Known Limitations

• If you manually unlocked some files inside an app during the 1.9.0 era, those still restore fine; but if you yourself locked an external app in Finder, that lock is cleared when the app moves back. AppPorts cannot tell the two apart, so re-apply it afterwards if needed.
• The file-owner warning currently covers data directory and custom folder migration; moving an app bundle does not write app data, so it is out of scope.

⚠️ "AppPorts" is damaged and can't be opened

If this appears after downloading AppPorts from an official release channel, it may be related to macOS quarantine checks for apps without Developer ID signing and notarization.

After confirming the download source, move AppPorts to the Applications folder and run:

:::shell
xattr -rd com.apple.quarantine /Applications/AppPorts.app

Migration Notes

• After upgrading, try one app restore that previously failed.
• If an app still cannot move back, send the error along with Help → Logs → Export Diagnostics to GitHub Issues; the package is redacted automatically.
• Keep using migrated directories as before: connect the external drive first, quit the app and eject the drive normally before disconnecting it, and keep a separate backup of important data.

遇到问题或有新的建议，欢迎通过 GitHub Issues 向我反馈。 / Share problems or suggestions with me through GitHub Issues.

Full Changelog: https://github.com/wzh4869/AppPorts/compare/1.9.1...1.9.2