Uninstally 详细部署与使用教程

Uninstally 是一款原生 macOS 卸载工具，能够彻底移除应用及其残留文件。本教程将覆盖 终端安装、图形界面安装、从源码构建 三种部署方式，以及后续的配置与使用。

📋 部署前准备

操作系统：macOS 14 (Sonoma) 或更高版本。
权限：建议您拥有管理员权限，以便授予应用所需的系统扩展和磁盘访问权限。
（可选）Homebrew：如果您希望通过命令行安装，需要先安装 Homebrew。

🚀 方式一：使用 Homebrew 安装（推荐）

这是最快捷、便于后续更新的安装方式。

1. 添加 Tap 仓库并安装

打开终端，执行以下命令：

1 2	# 添加第三方仓库并安装 brew install --cask gostonx/tap/uninstally

注意：首次使用 gostonx/tap 时，Homebrew 会提示您信任该 tap。您可以通过 brew trust gostonx/tap 命令永久信任它，以避免每次操作时的提示。

2. 更新与卸载

# 更新到最新版本
brew upgrade --cask uninstally

# 普通卸载
brew uninstall --cask uninstally

# 彻底卸载（同时删除应用支持文件和用户配置）
brew uninstall --cask --zap uninstally

📥 方式二：直接下载安装（适合非 Homebrew 用户）

如果您不使用 Homebrew，可以直接从 GitHub Releases 页面下载安装包。

下载 DMG 文件：访问项目的 Releases 页面，下载最新的 .dmg 文件。
安装应用：双击打开 .dmg 文件，将 Uninstally.app 拖拽到 Applications 文件夹中。
首次启动：由于应用来自未认证的开发者，macOS 可能会阻止运行。您可以：
- 右键点击 Uninstally.app，在菜单中选择“打开”，然后在弹出的对话框中确认。
- 或使用终端命令移除隔离属性：xattr -dr com.apple.quarantine /Applications/Uninstally.app

🔧 首次启动与关键配置

无论通过哪种方式安装，首次启动后都需要进行两项关键配置，才能获得完整功能。

1. 启用 Finder 扩展（实现右键卸载）

Uninstally 的核心便利功能之一是在 Finder 中右键点击应用即可卸载。

操作路径：打开 系统设置 → 通用 → 登录项与扩展 → 扩展。
操作：在“访达扩展”列表中找到 Uninstally Finder 并勾选启用。
提示：如果启用后 Finder 中仍未显示，可以按住 Option 键右键点击 Finder 图标，选择“重新启动”来刷新。

2. 授予完全磁盘访问权限（可选但推荐）

为了能够扫描 /Library 等受保护的系统目录，找到所有残留文件，您需要授予此权限。

操作路径：打开 系统设置 → 隐私与安全性 → 完全磁盘访问权限。
操作：点击锁形图标解锁，然后点击“+”号，将 Uninstally.app 添加到列表中并勾选。

🛠️ 方式三：从源码构建（开发者专用）

如果您希望基于源代码进行二次开发或尝鲜最新未发布特性，可以自行编译。

1. 克隆仓库

1 2	git clone https://github.com/gostonx/uninstally.git cd uninstally

2. 使用 Xcode 构建

此项目使用 Xcode 管理，您需要安装 Xcode 16 或更高版本。

# 打开 Xcode 项目
open Uninstally.xcodeproj

# 或通过命令行构建（调试版本）
xcodebuild -project Uninstally.xcodeproj -scheme Uninstally \
  -configuration Debug -destination 'platform=macOS' build

构建 Finder 扩展：Finder 扩展 UninstallyFinder 会作为主应用的一部分被一起编译。编译成功后，运行一次主应用，然后按照“首次启动与关键配置”中的步骤启用扩展即可。

3. 发布版本构建

如需构建用于分发的版本，您需要在 Xcode 项目设置中配置您的开发者团队（DEVELOPMENT_TEAM）并启用自动签名。更新机制（Sparkle）需要配置有效的 appcast 和 EdDSA 密钥，详见项目中的 docs/UPDATES.md。

📝 使用指南：如何彻底卸载应用

打开 Uninstally：您会看到一个按大小排序的应用列表。
查找应用：可以使用顶部的搜索框按名称或开发者筛选。
开始卸载：
- 方法一：在列表中找到应用，点击其右侧的卸载按钮（垃圾桶图标）。
- 方法二：在 Finder 中，右键点击任何 .app 应用文件，选择 “Uninstall with Uninstally”。
审查文件：在弹出的窗口中，Uninstally 会扫描并列出所有关联文件（缓存、偏好设置、容器、日志等）。您可以逐个勾选或取消想要删除的文件。
确认并完成：点击“卸载”按钮，应用及其所选残留文件将被彻底移除。

其他实用功能

批量卸载：在应用列表中，通过 Command 键多选，然后一次性卸载多个应用。
集合 (Collections)：您可以创建自定义标签页（如“办公软件”、“游戏试玩”），将应用分组管理。
最近卸载 (Recently Uninstalled)：可以查看卸载记录，并轻松恢复误删的应用及其文件。
残留扫描器 (Leftover scanner)：用于查找那些已被手动拖入废纸篓，但留下大量残留文件的应用。

🐛 常见问题与排障

问题	解决方法
Finder 右键菜单不显示	确保已在“系统设置”中启用了“Uninstally Finder”扩展。如仍不生效，尝试重启 Finder。
Gatekeeper 阻止应用运行	右键点击应用图标，选择“打开”，然后确认。或使用命令 `xattr -dr com.apple.quarantine /Applications/Uninstally.app`
Homebrew 提示 tap 不受信任	这是 Homebrew 的全局安全机制。运行 `brew trust gostonx/tap` 信任此 tap，或 `brew untap <其他不受信任的tap名>` 移除其他干扰项。
找不到 Homebrew 安装的包	确保已安装 Homebrew，然后完全退出并重新启动 Uninstally，以便应用重新检测 `brew` 命令路径。
残留扫描结果过多	在删除前请仔细审查每一项，确认其关联性。您可以在确认界面取消勾选任何不想删除的文件。