按空格没反应?FluxMarkdown的8个QuickLook排障技巧完整清单
按空格没反应?FluxMarkdown的8个QuickLook排障技巧完整清单
FluxMarkdown 是一款 macOS QuickLook 扩展工具,让你在 Finder 中选中 Markdown 文件后按空格,就能直接预览渲染好的排版、代码高亮与图表,而不用打开编辑器。但不少新手装完就遇到一个问题:按空格没反应,或者预览只显示纯文本。本文整理 8 个由浅入深的 QuickLook 排障技巧,帮你 10 分钟内恢复正常的 Markdown 空格预览。
排障前先确认:它"真的在工作"了吗?
在开始排查前,先做一次 10 秒验证:
- 在 Finder 里找到任意一个
.md文件 - 选中它,按 Space(空格)
- 看到带样式的预览(而不是纯文本)即为正常
如果这一步就失败了,下面 8 个技巧按顺序逐项尝试,大部分问题都能在第 1~4 步解决。
技巧1:先手动启动一次宿主 App(最容易被忽略)
macOS 的 QuickLook 扩展通常需要宿主 App 被打开过一次,系统才会完成扩展注册。很多人安装后直接按空格,自然没有反应。
操作步骤:打开 应用程序(Applications) 文件夹,双击启动一次 FluxMarkdown,出现欢迎窗口即可,不需要选择文件。
💡 如果你刚安装完,别忘了先把 app 拖进 Applications 文件夹。
技巧2:在系统设置中确认扩展已启用
如果按空格后仍是旧预览,说明扩展可能没被系统允许。
- 打开 系统设置(System Settings)
- 进入 扩展(Extensions)→ Quick Look(快速查看)
- 确认 FluxMarkdown / MarkdownPreview 相关项的开关已打开
这是官方新手指南中明确列出的关键一步,详见 docs/user/HELP.md。
技巧3:重启 Finder
Finder 会缓存 QuickLook 的扩展列表,重启它是最快、副作用最小的刷新方式:
- 在 Dock 上右键(或按住 Option 再点)Finder 图标
- 选择 Relaunch(重新启动)
- 回到文件上再按一次空格
技巧4:清理 QuickLook 缓存(按空格没反应的高频解法)
重启 Finder 无效时,打开"终端"运行以下命令,刷新 QuickLook 注册与缓存:
qlmanage -r
qlmanage -r cache
killall Finder
执行完回到 Finder 再按一次空格。很多"按空格没反应"的情况到这一步就恢复了。
技巧5:检查文件扩展名是否受支持
FluxMarkdown 不只识别 .md,它还支持 .markdown、.mdown、.mdwn、.mdc、.mkd 等多种扩展名(项目自带的测试文件就覆盖了大量格式,如 Tests/fixtures/test.mdc、Tests/fixtures/test.mkdn)。
如果你的文件扩展名比较特殊(比如 .livemd),可以先复制一份改名为 .md 测试,以此区分"扩展没生效"还是"这个扩展名不被识别"。
技巧6:处理"App is damaged / 无法验证开发者"
如果启动 App 时出现 App is damaged 提示,这是 macOS 对下载应用的安全隔离机制导致的,与 QuickLook 无关,但会让宿主 App 无法启动、进而扩展无法注册。
打开终端运行:
xattr -cr "/Applications/FluxMarkdown.app"
然后重新打开 App 即可。
技巧7:预览偶尔变成纯文本?先跑只读诊断脚本
扩展已注册、已启用,但按空格有时显示纯文本时,不要急着重装。项目内置了一个只读诊断脚本,它只收集系统版本、签名状态、扩展注册数量与启用状态等信息,不会读取你的文档内容,也不会修改任何系统设置:
./scripts/diagnose-quicklook.sh
# 可选:查询某个文件的 Spotlight UTI,使用完整路径
./scripts/diagnose-quicklook.sh --file "/absolute/path/to/example.md"
脚本位于 scripts/diagnose-quicklook.sh,官方说明见 docs/user/TROUBLESHOOTING.md。
看到输出中 extension_enabled_registrations 大于 0、签名为 passed,说明扩展本身没问题,问题大概率出在系统选择了其他预览插件或缓存上——此时回到技巧4清理缓存,并可把 FluxMarkdown 设为 .md 的默认打开方式(右键文件 → 显示简介 → 打开方式)。
技巧8:看系统日志,确认 Finder 到底调没调用你的扩展
前面都排过仍无解,就用日志做最终定位。开一个终端窗口:
log stream --style compact --predicate 'process == "MarkdownPreview"'
然后在 Finder 中对测试文件按空格,观察输出:
| 日志现象 | 说明 | 优先方向 |
|---|---|---|
| 完全没有任何启动记录 | Finder 没有调用该扩展 | 检查注册副本、扩展启用状态 |
有 preparePreviewOfFile,但没有 Renderer Handshake Received |
扩展启动了但渲染失败 | 检查扩展资源与 WebKit 错误 |
| 有握手且渲染完成 | 扩展工作正常 | 确认你看的窗口/文件是否正确 |
进阶的注册状态检查命令(pluginkit、qlmanage -p 直接调用扩展等)也在 docs/user/TROUBLESHOOTING.md 中有完整说明。
排障小贴士 📌
- 测试文件推荐:仓库自带的 Tests/fixtures/feature-validation.md 覆盖了标题、表格、YAML Front Matter 等元素,是验证渲染是否正常的现成样本
- 先保存故障现场再清缓存:按官方建议,先跑诊断脚本、保存故障时输出,再考虑重装或清缓存,避免丢失复现线索
- 仍解决不了:可以通过 App 菜单"帮助 → 报告问题"提交反馈,它会附带自动生成的诊断信息
按顺序走完这 8 个技巧,从"启动一次宿主 App"到"看日志定位",绝大多数 QuickLook 空格无反应或纯文本预览的问题都能定位并解决。祝预览愉快!🚀

