MacHunt：用原生 Swift 文件搜索工具，在 Mac 上快速找到文件

Mon, 10 Aug 2026 00:00:00 +0000

MacHunt 是一个在 Mac 本地建立文件名与元数据索引的搜索工具，原生 Swift Beta 将搜索、筛选、Quick Look 和文件操作放进同一个窗口。

有时记得文件名的一小部分，却忘了放在哪个目录。相比反复打开 Finder，一个能按路径、类型、日期继续缩小范围的结果列表更适合这种场景（见图 1）。

这个仓库 Fork 自 dacj4n/MacHunt。原来的 Tauri、React、Rust 版本仍保留在根目录；这里介绍的是 swift_beta/ 中的原生 Mac 版本。它目前标为 Beta，适合先用自己的常用目录试用。

图 1：原生版本的搜索列表、元数据列和筛选入口。截图来自项目仓库。

安装原生 Beta

前往 Releases，下载 Swift Beta 的 DMG，打开后拖入“应用程序”。当前提供的安装包面向 Apple 芯片 Mac，要求 macOS 14 或更新版本。它采用 ad-hoc 签名，尚未公证；首次启动受系统拦截时，请先核对下载来源，再按发布说明操作。

应用可以建立初始索引。第一次建议只选择自己需要的目录，并检查排除规则。扫描范围越大，初始化工作越多；某些目录也可能因为权限而无法读取。

例如只想找工作资料，可以先把“文稿”目录加入索引，把缓存或不需要搜索的下载目录排除。设置页能看到已索引项目数、实时监控状态和文件分类（见图 2）。先用小范围确认搜索结果符合预期，再考虑扩大范围。

图 2：在设置中查看索引状态与文件分类。截图来自项目仓库。

如果需要从命令行完整扫描，README 提供了下面的方式：

`1`	`"/Applications/MacHunt.app/Contents/Helpers/machunt" build --path /`

执行前退出 MacHunt，等索引完成后再打开。这里的 / 表示整个文件系统；只是想试用时，不必一开始就选择这样的范围。

先搜索，再筛选和预览

可以先输入有辨识度的文件名片段，再用目录、分类、日期或大小缩小结果。原生版本支持按片段、通配符或正则表达式、近似拼写搜索，也可以指定区分大小写。常用的文件分类可以修改，还能自己添加分类。

找到候选项后，先按空格调用系统 Quick Look，再决定打开还是到 Finder 查看周围文件（见图 3）。经常使用的结果可以固定保存。列表支持列选择、排序和多选；“移到废纸篓”也在操作菜单中，处理之前先核对路径。

图 3：先用系统 Quick Look 确认内容，再决定如何处理文件。

文件名搜索与内容搜索要分清

MacHunt 索引的是文件名、路径、日期、大小、Finder 标签和云端状态等元数据，不索引正文。如果记得的是文档中的一句话，它不能代替文档内容搜索。

原生索引保存在 ~/Library/Caches/MacHuntSwift/index.db。文件变动通过 FSEvents 增量维护；重建时先生成新数据库，完成后再替换旧索引，避免把半成品当作完整结果。

iCloud 仅在线文件也需要留意。扫描索引不会主动为了读取正文而下载它们，但打开或 Quick Look 预览可能触发系统下载。本地索引不等于搜索结果里的每个文件都已经离线保存。

用一份找不到的报告试一遍

假设只记得文件名中有 budget，却不知道它在下载目录还是项目文件夹。先输入这个片段，观察结果的路径列；如果同名结果很多，再限定到工作资料所在目录，筛选文档类别。随后按修改时间或大小排序，把明显无关的导出副本排到一边。

选中候选项按空格预览，确认标题和内容，再按需要打开原文件。对于想看旁边附件的情况，用“在 Finder 中显示”更直接。完成这次查找后，可以把经常回看的那份文件固定起来；固定项适合长期参考材料，但仍要保留能够区分项目和版本的名字。

普通片段搜索没有结果时，再考虑通配符或近似匹配。比如记得扩展名而忘了主体，可以用模式搜索；只记得零散字母时，近似匹配可以帮助缩小范围。先从最简单的一种模式开始，一次只改变一个条件，避免路径、类别和大小限制叠在一起，把真正的文件也排除掉。

用命令行搜索，不必重建另一份索引

应用内附的命令行工具和窗口共用索引，适合已经习惯在终端处理路径的人。下面先查询索引状态，再在“文稿”路径内搜索 budget，最后演示按模式查找 Swift 文件。完整路径可避免没有配置 PATH 时找不到命令：

cli="/Applications/MacHunt.app/Contents/Helpers/machunt"
"$cli" status
"$cli" search --path "$HOME/Documents" --json budget
"$cli" search --pattern '*.swift'

--json 方便让另一个脚本读取结果；只想自己看时，可以省略它。模式里的 *.swift 要保留引号，避免在 MacHunt 收到参数以前，就被当前 Shell 展开成当前目录的文件清单。这里做的是检索，不是再次运行全盘索引。

已知文件搜不到时，先查范围

先确认文件是否位于索引根目录内，有没有被排除规则或隐藏文件设置跳过，再清空搜索筛选条件。如果是外接盘，核对它是否已经连接并可在 Finder 打开。索引中存在路径，也不表示盘当前在线，或者文件已经从云端下载到本机。

知道完整文件名时，可以用它做一次简单查询；连这次也找不到，再检查索引状态和应用对目录的读取权限。不要一开始就扩大到全盘重建。先找出“没有扫描到”还是“条件把结果过滤掉”，通常更有助于理解自己的设置。

想自行构建时

原生版本的命令行工具与界面共用索引，还可以输出 JSON。没有另外配置 PATH 时，应使用应用包内工具的完整路径。

自行构建的入口是：

git clone https://github.com/Jingyuan-Zheng/MacHunt_SwiftUI.git
cd MacHunt_SwiftUI/swift_beta
swift test
scripts/build-app.sh release

构建需要带 Swift 6.2 或更新版本的 Xcode。不要把根目录旧 Tauri 版本的构建命令与 swift_beta/ 混用。

如果还想改善 Finder 的列表浏览，可以看批量开启文件夹大小显示。Beta 的最新功能与限制以项目 README 为准。

快速预览 on 小景