Mac 用 QLMarkdown 预览 Markdown 文件：按空格即可查看

结论

macOS Finder 的 Quick Look 原本不一定能直接预览 Markdown。安装 QLMarkdown 后，选中 .md 文件按空格，就可以先快速查看内容，不必为了确认一眼内容而打开 Obsidian、Typora 或其他编辑器。

这是一条很小、但很适合日常知识库工作的 Mac 方法：文件还在 Finder 里时，先用空格键确认内容，再决定是否打开编辑器继续处理。

一、适合什么场景？

如果你经常遇到下面这些情况，这个方法会比较顺手：

• 在 Finder 中快速确认某个 Markdown 文件是不是自己要找的那一篇；
• 查看下载的 Markdown 文档、README 或临时笔记；
• 不想为了看几行内容就启动完整的编辑器；
• 需要保留 Markdown 原文件，同时获得类似图片、PDF 的空格预览体验。

它解决的是“查看”问题，不是“编辑”问题。需要修改内容时，仍然应该用 Obsidian、VS Code、Typora 等编辑器打开。

二、安装 QLMarkdown

1. 用 Homebrew 安装

在真实终端中运行：

brew install --cask qlmarkdown

Homebrew 当前提供的版本是 1.5.2，要求 macOS 11 或更高版本。

2. 必要时移除下载隔离属性

如果 macOS 阻止应用打开，可以运行：

xattr -d com.apple.quarantine /Applications/QLMarkdown.app

如果终端提示没有这个属性，说明应用已经没有隔离标记，可以跳过这一步。不要把这条命令误解成“关闭 Mac 的整体安全机制”；它只处理这个应用包上的 com.apple.quarantine 属性。

3. 刷新 Quick Look

qlmanage -r

然后打开一次 QLMarkdown：

open -a QLMarkdown

打开一次的目的，是让应用完成首次启动和 Quick Look 生成器的注册。之后可以退出应用，不需要把它当作 Markdown 编辑器长期打开。

如果刷新后系统仍然没有识别扩展，可以手动注册一次：

pluginkit -a "/Applications/QLMarkdown.app/Contents/PlugIns/Markdown QL Extension.appex"
qlmanage -r

三、怎样使用？

1. 在 Finder 中找到一个 .md 文件；
2. 单击选中它；
3. 按空格键；
4. 在 Quick Look 窗口中快速阅读；
5. 需要修改时，再点击“打开方式”进入 Obsidian 或其他编辑器。

这套操作保留了 Finder 的原有习惯：图片、HTML、PDF 等文件可以按空格查看，Markdown 也加入同一套快速检查流程。

四、我这次实际执行了什么？

在本机完成了以下步骤：

Homebrew 安装 qlmarkdown 1.5.2
        ↓
确认 /Applications/QLMarkdown.app 已存在
        ↓
移除 com.apple.quarantine 属性
        ↓
打开一次 QLMarkdown
        ↓
执行 qlmanage -r 刷新 Quick Look

验证结果：

• brew list --cask --versions qlmarkdown 返回 qlmarkdown 1.5.2；
• /Applications/QLMarkdown.app 已安装；
• 应用上的隔离属性已清除；
• qlmanage -r 成功执行，系统返回 resetting quicklookd；
• pluginkit 已注册 org.sbarex.QLMarkdown.QLExtension (1.5.2)；
• 对本文 Markdown 文件执行 qlmanage -p 返回状态 0，Quick Look 预览请求已被系统接受；
• qlmarkdown_cli 已链接到 /opt/homebrew/bin/qlmarkdown_cli。

因此这不是只记录“网上看到的命令”，而是已经在本机完成安装和初始化的可复用方法。

五、遇到问题时怎样排查？

按空格仍然没有预览

按顺序重新执行：

qlmanage -r
open -a QLMarkdown

然后关闭并重新打开 Finder，再次选中 Markdown 文件测试。

xattr 报错

如果提示 No such xattr，通常表示没有需要删除的隔离属性，不必反复执行。重点检查应用是否存在：

ls -ld /Applications/QLMarkdown.app

只想阅读，不想安装额外工具

也可以把 TextEdit、妙言、Typora 或其他 Markdown 阅读器设置为默认打开程序。不过这会直接打开应用，体验上不等同于 Finder 的 Quick Look；QLMarkdown 更适合“先看一眼，再决定是否打开”。

六、边界与注意事项

• QLMarkdown 是 Quick Look 预览工具，不是 Markdown 编辑器；
• 它不会把 Markdown 转换或覆盖成其他格式，原文件仍然是原文件；
• xattr -d 只针对指定应用的隔离属性，执行前应确认路径确实是 /Applications/QLMarkdown.app；
• 如果公司电脑有安全策略，可能不允许自行移除隔离属性，应遵循设备管理规则；
• Homebrew cask 和 QLMarkdown 的版本会变化，安装前可以用 brew info --cask qlmarkdown 查看当前版本和系统要求。

来源

• 原始 X 帖子：向阳乔木分享 QLMarkdown 安装方法
• QLMarkdown 官方 GitHub 仓库
• Homebrew qlmarkdown cask