AppPorts Files

AppPorts v2.2.0 Build 51 更新说明（English below）

直链下载 · 赞助

感谢

感谢 trah01 承担了 2.2.0 里最重的一部分工作。应用库映像、侧栏导航与存储概览来自较早的一轮改动；随后的映像后台恢复、启动接回和完全磁盘访问引导，把整条路径补齐：登录后自动接回映像，点开应用前先准备好映像和数据卷，权限缺失时把图标直接拖进系统设置。这些改动横跨界面、后台代理和安装流程，也是这次大部分新功能的基础。

感谢 Souitou-iop 定位并修复了 macOS 27 上带下载标记的应用迁移失败的问题。这个问题在微信和浏览器下载的应用上必现，修复后不再因为一个无害的元数据标记中断整个迁移。

也谢谢每一位反馈问题、提供日志、分享使用经验和支持项目的朋友。

完全磁盘访问引导的图标拖拽交互改编自 DogSC（MIT），已在应用资源中保留其版权声明，并列入开源许可页。

总结

2.1.0 重新设计了应用迁移页面，并加入 AppPorts 的应用内更新；2.2.0 把迁移目标从物理外盘扩展到磁盘映像，让应用可以住进 NAS 或外置盘上的 APFS 映像，同时重做侧栏导航与存储概览，并补上安装位置检查、权限引导和一批后台挂载与离线访问的可靠性修复。

直接往 SMB 共享或 exFAT 外盘复制应用，会受服务端权限和元数据能力限制，签名、资源叉和扩展属性未必保得住。新的应用库映像改用 APFS 稀疏映像承载应用：映像按实际写入占用空间，可以创建在已挂载的共享或外盘里，也可以打开已有映像。挂载后会核对映像内的卷身份和承载存储身份，而不是靠卷名或路径猜测；失败时保留映像文件，不覆盖、不强制卸载，也不替你判断残留文件能否删除。

映像的可用性不只在打开 AppPorts 时维持。登录、卷变化和后台定时检查都会尝试接回当前选中的应用库；点开已迁移的应用时，本地入口会先运行一次无窗口准备，把映像和其中的数据卷接回，再启动真实应用。不再需要时，可以从侧栏的目标存储卸载映像，这次卸载会被记住：重启 AppPorts 或重新连接 NAS 都不会自动解除，只有明确重新挂载才恢复。

界面部分换成了可调宽度的侧栏：四个页面、任务中心、目标存储和本机/目标容量都收在一列里，内容区只保留当前页面的搜索和操作。同时删掉了侧栏里「已节省」的估算，因为外部内容的逻辑大小并不能证明本机真的释放了空间。

可靠性方面，新迁移和映像操作前会检查 AppPorts 是否在「应用程序」文件夹；完全磁盘访问的三个入口共用同一套图标拖拽引导；后台挂载代理不再把「命令返回 0」当作安装成功；macOS 27 上带 quarantine 的应用不再迁移失败；所有受管的离线入口统一为只读保护，微信拆分迁移后断盘登录不再因为路径访问被拒绝而崩溃。

升级提示

映像的暂停状态使用新格式，旧版读不懂。 2.2.0 会在存在映像暂停时写入版本 2 的暂停文件，2.1.0 及更早版本会拒绝读取并停止相关操作，而不是把它当成「没有暂停」。旧版同样不认识应用库映像记录。不要把降级或删除记录当作恢复方法。

已迁移应用的本地入口需要刷新一次，才会获得启动准备能力。 入口格式升级到 8：需要映像的应用会在入口里保存本机 AppPorts 路径，普通物理盘应用的入口则去掉这份依赖。升级后在映像在线的情况下打开一次 AppPorts、让应用列表完成扫描，入口才会刷新；未刷新前仍按原方式启动，映像未挂载时仍会提示外部存储不可用。

新迁移与映像操作要求 AppPorts 位于「应用程序」文件夹。 包括把应用数据迁出、创建/打开/重新挂载映像和打开权限引导。只查看列表、扫描应用和把已有数据迁回不受这条限制；从其他位置启动的后台自动恢复会静默跳过，不会反复弹窗。

卸载映像会持续暂停自动恢复。 重新插拔承载磁盘、重启 AppPorts 或重新连接 NAS 都不会解除。需要恢复时，使用「重新挂载映像」；如果只是想让应用重新生成本地数据，那是另一件事，不要用卸载映像代替。

新功能

应用库映像：把应用迁移到 NAS 或外置盘的 APFS 映像

侧栏「目标存储」右侧的「…」菜单提供创建、打开和重新挂载入口：

• 创建 APFS 映像：选择已挂载的 SMB 共享或外部存储，指定磁盘名称与最大容量（1–65536 GiB）。映像按实际写入占用空间，不会一次占满设定的上限。
• 打开已有映像：选择 .sparsebundle，把它作为应用库目标；重新挂载映像用于接回已记录但当前未挂载的映像。

挂载后会核对映像内的 APFS 卷 UUID 与承载存储身份（SMB 共享地址或底层卷 UUID），两者都对上才作为迁移目标。路径被占用、身份不符或命令失败时保留原有文件并停止，不会第二次附加同一映像，也不会为了「看起来成功」而强制卸载。

映像可以有多个可写卷：已有记录按保存的 UUID 定位，首次使用优先采用应用库路径对应的卷，否则使用第一个可写卷并保存下来，后续恢复沿用。挂载位置由系统按卷名决定；AppPorts 创建的映像卷名与文件名一致，通常是 /Volumes/<映像名>。

迁移本身仍走原有事务：准备、复制、完整校验、切换入口、清理，映像只是另一个目标位置。应用能否在共享上保留签名和元数据，由 APFS 负责，而不是由 SMB 或 exFAT 负责。

断线之后：登录、重连和打开应用时自动接回

映像的操作不要求 AppPorts 主窗口一直开着：

• 后台恢复：登录、卷变化和系统定时触发都会检查当前选中的应用库。SMB 重连使用系统已保存的凭据，不弹认证窗口；只读检查在独立进程里执行，单次最多 10 秒，避免网络查询把主程序卡在系统调用里。
• 只恢复选中的那个映像：历史映像不会自动挂载，需要时手动重新挂载。
• 打开应用前静默准备：通过新版入口打开已迁移应用时，入口先接回应用本体所在的映像，再挂载属于该映像的数据卷，然后才启动真实应用。准备成功不显示任何界面；失败才显示原有的「外部存储未连接」提示，并且不会先启动一个空数据的应用。
• 已就绪时不等锁：映像和数据卷都已按记录挂载时，走只读快速检查直接放行，不再因为其他迁移占着全局操作锁而等 5 秒后报错。
• 卸载映像：侧栏目标存储里的「卸载映像」只卸载映像本身，不请求 Finder 弹出承载磁盘，也不断开 SMB 共享。卸载前先保存暂停状态，后台、界面的自动恢复和启动准备都会遵守它。

映像失败时的处理是保守的：保留映像文件、保留暂停、报告错误，不自动删除、不强制卸载、不尝试修复。残留的未挂载附件只有在记录的 APFS UUID 核对成功后才会原地挂载，不会重复附加，也不会接管身份不明的设备。

完全磁盘访问：把 AppPorts 图标拖进系统设置

完全磁盘访问的三个入口现在共用同一套引导：打开系统设置的同时，在窗口旁显示一个不抢焦点的浮窗，左边是真实的 AppPorts 图标，可以直接拖进「完全磁盘访问权限」列表；右边写明「找不到 AppPorts？」和操作说明。

浮窗跟随系统设置窗口移动，下方放不下时移到上方，上下都放不下时贴着窗口底边内侧显示，不遮挡标题栏和窗口控制按钮。切换到无关应用、关闭系统设置或拖入被接受后，浮窗自动隐藏。

拖入被系统接收只代表文件被接收，不代表已经授权。AppPorts 仍以实际的完全磁盘访问读取探针为准，回到应用后刷新状态。

界面与使用体验

• 侧栏导航。 主页面改为可调宽度的原生分栏，左侧固定承载「应用 / 工具目录 / 应用数据 / 目录迁移」四个入口、任务中心、目标存储、容量概览和设置/刷新/外观；内容区只保留当前页面的搜索、筛选和业务操作。侧栏宽度可拖动调整。
• 任务中心入口带状态。 数字徽标表示排队和执行中的未结束任务数，归零时隐藏；存在需要处理的任务时另外显示警告标记。完成历史不计入数字。
• 本机与目标容量。 侧栏底部显示本机数据卷和所选目标所在卷的已用、空余与使用率，每 5 秒在后台刷新；读取失败显示「无法读取」，不拿 0 顶替未知值。目标是映像时，目标区域显示映像名称与挂载路径。容量只用于展示，不参与迁移准入或删除授权。
• 去掉「已节省」估算。 外部内容的逻辑大小不能证明本机实际释放了多少空间，侧栏不再显示这个数字，也删除了它背后的目录遍历和缓存；应用数据页的「可释放」统计保留，仍只用于展示。
• 页面切换更直接。 取消整页淡入和位移动画，已打开的页面保留内容和状态，切换时不再让大列表整体重排。目录迁移页复用应用页的面板、列布局、行背景、悬停和菜单样式，行内次要操作收进「更多操作」菜单。
• 应用数据页更紧凑。 顶部去掉重复的标题行，搜索框上移，列表区因此更宽松。
• 窗口与外观。 窗口改为隐藏标题栏的全高布局，并设定固定的初始尺寸；外观可在侧栏切换「跟随系统 / 浅色 / 深色」。
• 统一工具栏与弹窗。 各页面右侧工具栏控件、迁移与恢复相关弹窗的字体层级统一，减少同类信息在不同页面的样式差异。
• 补齐多语言。 本次新增的映像、权限引导、容量与安装位置文案已覆盖全部 22 种语言。

扫描与检查改进

迁移前的来源核对移到了任务里。 点击迁移不再先清空列表、重新扫描页面再打开确认框；确认框中的大小仍是估算值。新迁移任务在取得资源与操作锁、确认应用退出之后，才在原有的准备阶段重新发现来源、核对身份并强制测量所选目录；来源消失、权限不足或读取不完整都会在复制前停止。切换页面不会取消已提交的迁移。

目录大小统计更快，也更克制。 数据目录大小改用系统原生遍历读取已采集的文件大小，只累计普通文件逻辑长度，跳过子挂载、不跟随嵌套软链；已核对的离线入口会作为跳过集合，祖先继续保持「不完整」并拒绝写入缓存，不会把缺盘算成完整的 0 字节。应用列表的体积统计最多四路并发，一个慢应用不再拖住后面的行。合成目录上的统计耗时明显下降，但外置盘、网络盘和机械盘上的收益会不同，这不代表迁移整体变快。

完整内容校验改用有界批量队列。 同一目录最多预取 32 个文件描述符，固定四个工作线程领取任务，工作线程复用至多 1 MiB 的读取缓冲，不再为每个文件重新分配和清零。每个文件仍然读取全部逻辑字节并计算 SHA-256，准备、切换、清理和恢复的校验次数不变——这次改的是调度开销，不是校验标准。

离线保护统一到一套策略。 所有由 AppPorts 接管的离线入口，在卸载或断盘后都是只读可访问：应用能读取和进入空目录，新建文件与目录仍被拒绝。旧版留下的完全不可访问目录，会在核对身份和空内容后升级；仍挂载的业务卷不会为了升级被主动卸载。

修复

macOS 27 与迁移

带 quarantine 的应用在 macOS 27 上迁移必失败 — 复制完成后，校验阶段会对副本的 quarantine 标记调用 removexattr，而 macOS 27 对所有进程都返回权限拒绝，整个迁移被一个无害的元数据标记终止。微信（Sparkle 更新）和浏览器下载的应用都会命中。现在复制清单不再记录、比较或回放 quarantine，副本可能携带系统附加的标记，是否允许打开仍由 macOS 判断；其他属性、内容、身份或权限的差异仍会照常拒绝。

后台挂载与系统归属

后台挂载代理处于禁用状态，却记录为安装成功 — 旧流程只相信 bootstrap 或兼容 load 的退出码，于是 plist 在、服务却被系统停用的情况会被当成安装成功，登录和插盘后的自动挂载也就一直不生效。现在安装和启动校准会先对本用户域的服务执行 enable，加载后再用 print 确认服务确实注册；定义没变时保留现有进程，不再为一次假成功重写配置。

系统设置里的后台项只显示开发者姓名 — LaunchAgent 增加应用关联标识，系统设置可以把它归到 AppPorts 名下，不再是一串看不出用途的开发者名称。旧缓存不一定立刻消失，需要安装新版并重新注册后确认。

离线与权限

微信拆分迁移后，外盘断开会登录崩溃 — 媒体入口此前仍是完全不可访问的权限，微信登录后在路径解析阶段拿到权限错误，未处理的异常最终触发崩溃。现在这类入口与其他受管入口一样是只读保护：可以读取和遍历，写入仍被拒绝；不会因此允许微信在本机建立新的媒体目录。缺盘时容量继续标记为未知或不完整，不缓存成完整结果，也不引导用户补权限。

已知限制

• 应用库映像不是备份。 映像损坏、NAS 故障或网络 I/O 问题仍需独立备份；同一映像请只在一台 Mac 上写入。
• 自动恢复只针对当前选中的一个映像。 历史映像要手动重新挂载；退出 AppPorts 也不会卸载映像，迁出的应用可能仍在运行。
• 凭据和挂载仍由系统决定。 系统没有保存 SMB 凭据时需要在 Finder 重新连接，加密卷要先解锁，底层磁盘要由 macOS 挂载。
• 映像的挂载路径依赖卷名。 在 Finder 里改了卷名，身份核对会失败；把卷名改回与保存路径一致即可恢复。
• 需要重签名的应用仍需要物理外盘。 签名原包备份位置继续排除磁盘映像，映像不能替代原包保存。
• 离线只读保护不保证应用可用。 它解决的是已确认的路径权限触发条件，不保证微信或其他应用在缺少外盘数据时仍能正常启动、登录或使用；本地可读空目录不代表数据已迁回。

---

AppPorts v2.2.0 Build 52 Release Notes (English)

Direct Download · Sponsor

Thanks

Thank you to trah01 for the largest share of the work in 2.2.0. The app library image, the sidebar and the storage overview came from an earlier round of changes; the later image recovery, launch preparation and Full Disk Access guide completed the path — bringing an image back after login, preparing the image and its data volumes before an app opens, and letting people drag the app into System Settings when permission is missing. This work spans the interface, the background agent and the installation flow, and it forms the basis of most of the new features in this release.

Thank you to Souitou-iop for tracking down and fixing migration failures for quarantined apps on macOS 27. The problem reproduced every time with WeChat and browser-downloaded apps, and migrations no longer stop over a harmless metadata marker.

Thank you as well to everyone who reports issues, provides logs, shares their experience and supports the project.

The icon-dragging interaction in the Full Disk Access guide is adapted from DogSC (MIT). Its copyright notice is retained in the app resources and listed on the Licenses page.

Summary

2.1.0 redesigned the app migration page and added in-app updates for AppPorts itself. 2.2.0 extends migration targets from physical drives to disk images, so apps can live in an APFS image on a NAS or external drive, while also rebuilding sidebar navigation and the storage overview and adding installation-location checks, a permission guide and a set of reliability fixes for background mounting and offline access.

Copying an app directly to an SMB share or an exFAT drive is limited by server permissions and metadata support: signatures, resource forks and extended attributes may not survive. The new app library image carries apps inside an APFS sparse image instead. The image grows with actual writes, can be created on a mounted share or external drive, and existing images can be opened. After mounting, AppPorts verifies the volume identity inside the image and the identity of the backing storage instead of guessing from volume names or paths. On failure it keeps the image file, does not overwrite, does not force-detach and does not decide for you whether leftovers can be deleted.

An image is not only available while AppPorts is open. Login, volume changes and a background timer all try to bring back the currently selected app library. When you open a migrated app, its local entry runs a windowless preparation step that reattaches the image and the data volumes inside it before launching the real app. When the image is no longer needed, you can unmount it from Destination Storage in the sidebar, and that choice is remembered: restarting AppPorts or reconnecting the NAS does not clear it, and only an explicit remount resumes automatic handling.

The interface now uses an adjustable sidebar: the four pages, Task Center, Destination Storage and local and destination capacity all live in one column, and the content area keeps only the search and actions for the current page. The "space saved" estimate in the sidebar is gone, because the logical size of external content does not prove that local space was actually freed.

For reliability, new migrations and image operations now check that AppPorts is in the Applications folder; the three Full Disk Access entry points share one icon-dragging guide; the background mount agent no longer treats "the command returned 0" as a successful installation; apps carrying quarantine markers no longer fail to migrate on macOS 27; and all managed offline entries now use one read-only protection policy, so WeChat no longer crashes at login after a split migration when the external drive is offline.

Upgrade Notes

Image pause state uses a new format that older versions cannot read. When an image pause exists, 2.2.0 writes a version 2 pause file. 2.1.0 and earlier refuse to read it and stop the related operation instead of treating it as "no pause". Older versions also do not recognise app library image records. Do not treat downgrading or deleting records as a recovery method.

Migrated apps need one entry refresh to gain launch preparation. Entries are upgraded to format 8: apps that need an image store the local AppPorts executable path in their entry, while entries for apps that live entirely on a physical drive lose that dependency. After upgrading, open AppPorts once with the image online and let the app list finish scanning. Until then, entries launch the old way and still report unavailable storage when the image is not mounted.

New migrations and image operations require AppPorts to be in the Applications folder. This covers migrating app data out, creating, opening and remounting images, and opening the permission guide. Browsing lists, scanning apps and restoring existing data are not restricted; automatic background recovery started from another location skips silently instead of showing repeated prompts.

Unmounting an image keeps automatic handling paused. Reconnecting the backing disk, restarting AppPorts or reconnecting the NAS does not clear it. Use "Mount Image Again" to resume. If you only want an app to regenerate local data, that is a different operation; do not use image unmounting as a substitute.

New Features

App Library Images: Migrate Apps into an APFS Image on a NAS or External Drive

The "…" menu in Destination Storage provides creation, opening and remounting:

• Create APFS Image: choose a mounted SMB share or external drive and specify a disk name and maximum capacity (1–65536 GiB). The image uses space as data is written and does not take the whole maximum up front.
• Open Existing Image: choose a .sparsebundle and use it as the app library target. Mount Image Again brings back an image that is recorded but not currently mounted.

After mounting, AppPorts verifies the APFS volume UUID inside the image and the identity of the backing storage (the SMB share address or the underlying volume UUID). Only when both match is the image used as a migration target. If a path is occupied, an identity does not match or a command fails, existing files are kept and the operation stops. It does not attach the same image twice and does not force-detach anything to look successful.

An image may contain more than one writable volume. Existing records are located by the saved UUID; on first use AppPorts prefers the volume at the app library path, otherwise uses the first writable volume and saves it for later recovery. The mount location is chosen by the system from the volume name. Images created by AppPorts use the file name as the volume name, so the path is usually /Volumes/<image name>.

Migration itself still uses the existing transaction — prepare, copy, full verification, switch the entry, clean up — the image is simply another destination. Whether an app keeps its signature and metadata on a share is now APFS's responsibility rather than SMB's or exFAT's.

After a Disconnect: Bringing the Image Back at Login, on Reconnect and Before Launch

Image handling does not require the AppPorts window to stay open:

• Background recovery: login, volume changes and a system timer all check the selected app library. SMB reconnection uses credentials already saved by the system and never shows an authentication window. Read-only checks run in a separate process with a 10-second limit, so a network query cannot block the main app inside a kernel call.
• Only the selected image is restored. Historical images are not mounted automatically; remount them manually when needed.
• Windowless preparation before launch: when a migrated app is opened through a new entry, the entry first reattaches the image containing the app, then mounts the data volumes belonging to that image, and only then launches the real app. Success shows no interface; failure shows the existing "external storage not connected" prompt and does not start an app with empty data.
• No lock wait when already ready: if the image and data volumes are mounted as recorded, a read-only readiness check allows the launch immediately instead of failing after 5 seconds because another migration holds the global operation lock.
• Unmount Image: the action in Destination Storage unmounts only the image. It does not ask Finder to eject the backing disk or disconnect the SMB share. The pause state is saved first, and background recovery, in-app recovery and launch preparation all respect it.

Failures stay conservative: the image file and the pause are kept, the error is reported, and nothing is deleted, force-detached or repaired automatically. Leftover unmounted attachments are mounted in place only after their recorded APFS UUID is verified; they are never attached twice, and devices with unknown identity are never taken over.

Full Disk Access: Drag the AppPorts Icon into System Settings

All three Full Disk Access entry points now share one guide. When System Settings opens, a non-activating panel appears next to the window with the real AppPorts icon on the left, ready to be dragged into the Full Disk Access list, and "Can't find AppPorts?" with instructions on the right.

The panel follows the System Settings window, moves above it when there is no room below, and sits just inside the bottom edge when neither side fits, without covering the title bar or the window controls. It hides when you switch to an unrelated app, when System Settings closes, or once the drag is accepted.

An accepted drag only means the system accepted the file, not that permission was granted. AppPorts still relies on an actual read probe and refreshes the state when you return to the app.

Interface and Usability

• Sidebar navigation. The main window uses an adjustable native split view. The sidebar holds the four sections (Apps, Tool Directories, App Data, Directory Migration), Task Center, Destination Storage, capacity and Settings/Refresh/Appearance; the content area keeps only the current page's search, filters and actions. The sidebar width is draggable.
• Task Center status at the entry. A numeric badge shows queued and running unfinished tasks and disappears at zero; tasks that need attention show a separate warning marker. Completed history is not counted.
• Local and destination capacity. The bottom of the sidebar shows used space, free space and usage for the Mac data volume and the selected destination volume, refreshed in the background every 5 seconds. Failures show "Unreadable" rather than zero. When the destination is an image, the Destination Storage section shows the image name and mount path. Capacity is display-only and does not authorize migration or deletion.
• The "space saved" estimate is gone. The logical size of external content cannot prove how much local space was freed, so the number, its directory traversal and its cache were removed. The "reclaimable" summary on the App Data page remains display-only.
• Direct page switching. Whole-page fades and offsets are removed, opened pages keep their content and state, and large lists no longer recompose on every switch. The Directory Migration page now reuses the Apps page panel, column layout, row backgrounds, hover and menu styles, with secondary row actions in a "More Actions" menu.
• Tighter App Data page. The duplicate title row is gone and the search field moved up, giving the list more room.
• Window and appearance. The window uses a hidden title bar with full-height content and a fixed initial size; appearance can be switched in the sidebar between System, Light and Dark.
• Unified toolbars and dialogs. Right-side toolbar controls and the typography of migration and recovery dialogs are consistent across pages.
• More complete translations. New strings for images, the permission guide, capacity and installation location cover all 22 languages.

Scanning and Safety Checks

Source verification moved into the migration task. Clicking Migrate no longer clears the list and rescans the page before showing the confirmation, and the sizes in that dialog are still estimates. After acquiring resources and the operation lock and confirming the app has quit, the new task rediscovers the source in the existing preparation phase, verifies identity and forcibly measures the selected directories. A missing source, insufficient permissions or an incomplete read stops the task before copying. Switching pages no longer cancels a submitted migration.

Directory sizes are faster and more restrained. Data directory sizes now use the native system traversal and the file sizes it already collects, counting only regular-file logical length, skipping nested mounts and not following nested symlinks. Verified offline entries become a skip set: ancestors stay incomplete and refuse to write a cache entry, so a disconnected drive is never counted as a complete 0 bytes. App size statistics run at most four at a time, so one slow app no longer holds up the rows after it. Synthetic directories are measured noticeably faster, but gains on external, network and mechanical drives will differ, and this does not make migration as a whole faster.

Full content verification uses a bounded batch queue. A directory prefetches at most 32 file descriptors, four workers take items from the queue, and each worker reuses a read buffer of up to 1 MiB instead of allocating and zeroing one per file. Every file is still read in full and hashed with SHA-256, and the number of verification passes for preparation, switching, cleanup and recovery is unchanged. This changes scheduling overhead, not the verification standard.

Offline protection uses one policy. Every offline entry managed by AppPorts is read-only accessible after unmounting or disconnection: apps can read and traverse the empty directory, while new files and directories are still refused. Legacy directories that were completely inaccessible are upgraded after identity and empty-content checks, and mounted business volumes are never unmounted just to perform the upgrade.

Fixes

macOS 27 and Migration

Apps with quarantine markers always failed to migrate on macOS 27 — after copying, verification called removexattr on the copy's quarantine marker, which macOS 27 refuses for every process. A harmless metadata marker aborted the whole migration, and it reproduced with WeChat (updated through Sparkle) and browser-downloaded apps. The copy manifest no longer records, compares or replays quarantine. Copies may carry the marker the system attached, and whether an app may open is still up to macOS. Differences in other attributes, content, identity or permissions are still rejected.

Background Mounting and System Attribution

The background mount agent was disabled but recorded as installed — the old flow trusted the exit code of bootstrap or the compatibility load, so a plist that existed while the service was disabled by the system counted as installed and automatic mounting never worked after login or reconnecting a drive. Installation and startup calibration now enable the exact service in the user domain first, then confirm registration with print after loading. Unchanged definitions keep their existing process, and a false success no longer rewrites the configuration.

The background item in System Settings showed only the developer name — the LaunchAgent now has an associated bundle identifier, so System Settings can attribute it to AppPorts instead of an unfamiliar developer name. Old caches may not disappear immediately; install the new version and re-register to confirm.

Offline Access and Permissions

WeChat crashed at login after a split migration when the external drive was offline — its media entries were still completely inaccessible, and WeChat received a permission error during path resolution, ending in an unhandled exception. Those entries now use the same read-only protection as other managed entries: readable and traversable, still refusing writes, and still unable to create new local media directories. Capacity stays unknown or incomplete, is not cached as complete, and does not prompt for missing permissions.

Known Limitations

• An app library image is not a backup. Image corruption, NAS failures and network I/O problems still require independent backups. Write to one image from one Mac at a time.
• Automatic recovery covers only the currently selected image. Historical images must be remounted manually, and quitting AppPorts does not unmount the image; migrated apps may still be running.
• Credentials and mounts remain the system's responsibility. If the system has no saved SMB credentials, reconnect in Finder; encrypted volumes still need unlocking; the underlying disk must be mounted by macOS.
• The image mount path depends on the volume name. Renaming the volume in Finder makes identity verification fail; renaming it back to the saved path restores it.
• Apps that need re-signing still need a physical drive. Signature backup locations continue to exclude disk images, so an image cannot replace the original-package backup.
• Offline read-only protection does not guarantee an app works. It addresses the confirmed path-permission trigger. It does not guarantee that WeChat or other apps can start, sign in or function without their external data, and a readable empty local directory does not mean the data was restored locally.

---

What's Changed

• feat: 新增磁盘映像应用库并优化扫描与迁移 by @trah01 in https://github.com/wzh4869/AppPorts/pull/102
• fix: 兼容 macOS 27 受保护的 quarantine，修复带标记应用迁移失败 by @Souitou-iop in https://github.com/wzh4869/AppPorts/pull/103
• feat: 完善应用库映像恢复、启动入口与权限引导 by @trah01 in https://github.com/wzh4869/AppPorts/pull/104

New Contributors

• @Souitou-iop made their first contribution in https://github.com/wzh4869/AppPorts/pull/103

Full Changelog: https://github.com/wzh4869/AppPorts/compare/2.1.0...2.2.0