按空格没反应?FluxMarkdown的8个QuickLook排障技巧完整清单

原创2026-10-12 17:52:501,767 阅读

按空格没反应?FluxMarkdown的8个QuickLook排障技巧完整清单

FluxMarkdown 是一款 macOS QuickLook 扩展工具,让你在 Finder 中选中 Markdown 文件后按空格,就能直接预览渲染好的排版、代码高亮与图表,而不用打开编辑器。但不少新手装完就遇到一个问题:按空格没反应,或者预览只显示纯文本。本文整理 8 个由浅入深的 QuickLook 排障技巧,帮你 10 分钟内恢复正常的 Markdown 空格预览。

FluxMarkdown 在 Finder 中按空格即可预览 Markdown 的 QuickLook 效果

排障前先确认:它"真的在工作"了吗?

在开始排查前,先做一次 10 秒验证:

  1. 在 Finder 里找到任意一个 .md 文件
  2. 选中它,按 Space(空格)
  3. 看到带样式的预览(而不是纯文本)即为正常

如果这一步就失败了,下面 8 个技巧按顺序逐项尝试,大部分问题都能在第 1~4 步解决。

技巧1:先手动启动一次宿主 App(最容易被忽略)

macOS 的 QuickLook 扩展通常需要宿主 App 被打开过一次,系统才会完成扩展注册。很多人安装后直接按空格,自然没有反应。

操作步骤:打开 应用程序(Applications) 文件夹,双击启动一次 FluxMarkdown,出现欢迎窗口即可,不需要选择文件。

FluxMarkdown QuickLook 扩展的安装窗口,拖拽到 Applications 即可安装

💡 如果你刚安装完,别忘了先把 app 拖进 Applications 文件夹。

技巧2:在系统设置中确认扩展已启用

如果按空格后仍是旧预览,说明扩展可能没被系统允许。

  1. 打开 系统设置(System Settings)
  2. 进入 扩展(Extensions)→ Quick Look(快速查看)
  3. 确认 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 空格无反应或纯文本预览的问题都能定位并解决。祝预览愉快!🚀

登录后查看全文
flux-markdown