摘要SpacePeek 安装后最常见的 6 个问题——装完按空格没反应、和其他 Quick Look 扩展冲突、Pro 购买后没解锁、大文件夹扫描慢、Git 仓库检测不出来、偏好设置找不到——本文逐一给出排查步骤和解决方案。如果你遇到任何 SpacePeek 使用问题先看这篇。本文信息基于 SpacePeek v1.22026-07-10及 macOS 15.0 Sequoia 编写。如后续版本有变更请以 GitHub Issues 和 App Store 更新日志为准。一、前言SpacePeek 装完之后最常见的反应不是好用是怎么没反应SpacePeek 是一个 macOS Quick Look 扩展——这意味着它的启动机制和普通 App 不同。普通 App 有一个图标双击打开。Quick Look 扩展没有——它寄生在 Finder 的按空格预览流程里。这个机制的好处是无缝融入系统不需要打开任何 App。坏处是一旦它不工作你不知道去哪里排查。以下 6 个问题是我自己在使用过程中遇到的、以及在各平台的用户反馈中收集到的。每一个都有明确的排查步骤和解决方案。二、6 个问题的排查指南问题 1装完 App选中文件夹按空格还是蓝色文件夹图标症状从 App Store 下载了 SpacePeek启动了一次然后选中文件夹按空格——出来的还是系统默认的蓝色文件夹图标和文件夹三个字。原因macOS 对第三方 Quick Look 扩展的安全策略非常保守。你下载了 App、启动了 App不代表 Quick Look 扩展被自动启用了。你需要在系统设置中手动打开。解决步骤系统设置 → 通用 → 登录项与扩展 → 找到Quick Look快速查看 → 找到 SpacePeek → 打开开关如果列表里有多个 Quick Look 扩展把 SpacePeek 拖到最顶部确保它优先于其他文件夹预览扩展。验证设置完毕之后选中任意文件夹按空格。应该看到 SpacePeek 的预览面板大小、文件数、饼图而不是系统默认的蓝色文件夹图标。如果仍然不生效# 检查 Quick Look 扩展是否注册成功pluginkit-m-v-pcom.apple.quicklook.preview|grep-ispacepeek# 如果有输出 → 说明扩展已注册可能是优先级问题# 如果无输出 → 卸载重新安装问题 2有时候正常、有时候还是系统默认预览症状SpacePeek 的预览面板有时出现、有时不出现好像随机抽风。同一个文件夹按两次空格可能出来两个不同的界面。原因你的 Mac 上装了多个文件夹预览类的 Quick Look 扩展比如 Folder Preview、Folder Quick Look、PeekX 等。当多个扩展都注册了public.folder这个 UTI 时macOS 会按扩展列表的顺序选择第一个——但有时系统会选择困难导致随机行为。解决步骤系统设置 → 通用 → 登录项与扩展 → Quick Look → 把 SpacePeek 拖到列表最顶部 → 把其他文件夹预览扩展Folder Preview / Folder Quick Look 等关掉如果你需要保留其他扩展的某些功能比如 Folder Preview 的压缩包预览可以保持它们开启但确保 SpacePeek 排在第一位。问题 3Pro 购买了但没解锁症状在 App Store 点购买 SpacePeek Pro$1.99钱扣了但预览面板里的 Pro 功能无限层级下钻仍然不能用。原因IAPIn-App Purchase状态检测偶尔会有缓存问题。App 可能没有立即拉取到最新的购买状态。解决步骤1. 退出 SpacePeek如果它有独立窗口的话 2. App Store → 点击左下角你的头像 → 找到 SpacePeek → 确认购买状态显示已购买 3. 重启 Mac简单粗暴但有效——强制 App 重新拉取 IAP 状态v1.2 版本已经改进了 Pro 解锁的可靠性检测。如果你还在用旧版本App Store 更新到最新版可解决大部分此类问题。如果仍然不生效在 github.com/wangfu91/SpacePeek/issues 提交 Issue附上你的购买凭证和 macOS 版本。问题 4大文件夹扫描时感觉卡住了症状选中一个文件数量很多的文件夹比如含有 20 万文件的 node_modules按空格后SpacePeek 的预览窗口弹出了一两秒然后才显示结果——中间好像卡住了。原因SpacePeek 的扫描引擎是 Rust 编写的并行遍历非阻塞但在扫描完成之前预览窗口确实需要等待结果。对于超大文件夹遍历本身是有物理耗时上限的。这不是 bug是物理限制。如何判断是否正常v1.2 版本新增了实时扫描进度条。如果进度条在动说明扫描正在进行中不是卡住。以下是大致耗时参考文件夹规模预期耗时1000 文件 1 秒10000 文件1-2 秒50000 文件2-5 秒100000 文件5-15 秒如果耗时远超上表可能是其他后台进程正在同时访问该文件夹如 Time Machine 备份、Spotlight 索引、杀毒软件扫描等形成了 I/O 竞争。问题 5Git 仓库识别不出来症状选中一个 Git 项目文件夹按空格SpacePeek 的预览面板没有显示 Git 分支名、提交信息等——只在 Overview 视图里出现了。原因可能是你没切到 Overview 视图。解决步骤SpacePeek v1.2 有双视图 → Overview 视图默认显示文件夹总览、大小、饼图 → Contents 视图显示文件列表 Git 仓库的元数据显示在哪个视图取决于你是否选中了项目的根 .git 目录还是项目文件夹。 选中包含 .git 的根目录才会触发 Git 检测。另外如果.git文件夹被 Finder 隐藏了macOS 默认隐藏你仍然可以正常触发——选中项目根文件夹按空格Overview 视图应该自动显示 Git 信息。如果仍然不显示确认.git目录确实存在在终端里ls -la确认。问题 6我想改快捷键 / 偏好设置但找不到设置面板症状SpacePeek 没有独立窗口、没有 Dock 图标、没有菜单栏图标。我想找它的设置面板找不到。原因SpacePeek 是一个 Quick Look 扩展不是一个独立 App。它的设计理念就是不存在——直到你按空格的那一瞬间。因此目前版本没有独立设置面板。当前可以做的事情开启/关闭 SpacePeek系统设置 → 通用 → 登录项与扩展 → Quick Look查看版本号App Store → 点击头像 → App 列表 → SpacePeek提交反馈GitHub Issues关于快捷键SpacePeek 没有自己的快捷键——它复用的是 macOS Quick Look 的系统快捷键空格键。如果你想改 Quick Look 的快捷键这在 macOS 中没有原生支持但可以通过系统设置 → 键盘 → 键盘快捷键 → 找到快速查看来调整。三、问题速查表问题最可能原因最快解决方式按空格没反应Quick Look 扩展未启用系统设置 → 扩展 → Quick Look → 开随机不生效多个 Quick Look 扩展冲突把 SpacePeek 拖到最顶部Pro 买完没解锁IAP 缓存重启 Mac扫描卡住大文件夹正常耗时v1.2 有进度条看它在动就正常Git 检测不出来可能没切到正确视图确认选中了项目根文件夹找不到设置面板没有独立设置面板这是设计非 bug四、总结三点SpacePeek 的问题 90% 和 Quick Look 扩展的启用/优先级有关。系统设置 → 通用 → 登录项与扩展 → Quick Look → 检查 SpacePeek 是否开启 是否排第一。搞不定的话先确认这两步。macOS 的 Quick Look 扩展机制和普通 App 完全不同——没有 Dock 图标、没有独立设置、需要手动启用。这不是 SpacePeek 的问题是所有 Quick Look 扩展的共性。如果排查完以上 6 个问题仍然无法解决在 GitHub Issues 提交反馈。开发者是个人独立维护响应速度取决于时差和工作量。版本与链接项目信息SpacePeek 版本v1.2macOS15.0 SequoiaApp StoreSpacePeekGitHub Issueswangfu91/SpacePeek/issues你安装 SpacePeek 的时候遇到过什么问题评论区告诉我——如果是我漏掉的我补进下一版 FAQ。
