MiaoYan 评测：本地优先的 macOS Markdown 笔记应用，Swift 6 原生实现
该项目围绕「tw93/MiaoYan」构建，面向真实业务场景提供可复用的开源实践方案，支持稳定落地与可扩展的项目实践。
秒懂
- 它是什么？
- MiaoYan 是一款面向 macOS 的轻量级 Markdown 笔记应用，采用本地优先架构，通过文件夹同步实现跨设备协作。本文基于其 README 与仓库信息，分析其设计取舍、安装方式与适用边界。
- 适合谁用？
- MiaoYan 适合那些坚持纯 Markdown 编辑、反感 Electron 应用内存占用、且愿意自己管理云盘同步的 macOS 用户。它不适合需要 WYSIWYG 即时渲染、或依赖内置 WebDAV 同步的笔记重度用户。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 9 天前。
- 用什么语言写的？
- 主要是 Swift（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
本地优先的 Markdown 笔记应用，解决什么问题
MiaoYan 解决的是 macOS 上 Markdown 笔记工具的两类痛点：一是 Electron 应用带来的内存与启动开销，二是云端同步服务对用户数据的隐式收集。它明确宣称 local-first，不登录 WebDAV 或云盘账号，所有数据以普通 Markdown 文件形式存放在用户指定的文件夹中。目标用户是那些已经习惯用 Markdown 写作、需要快速记录且在意数据自主权的开发者或文字工作者。它不提供数据库、不锁定格式，你的笔记就是一堆 .md 文件，随时可以用其他工具打开。
Swift 6 原生架构与分屏编辑的取舍
MiaoYan 用 Swift 6 编写，对比 Electron 方案，在启动速度和内存占用上有天然优势。但更值得关注的是它的编辑模式选择：它提供分屏编辑与预览，而非 Typora 那种 WYSIWYG。README 中明确解释了原因：纯 Markdown 编辑体验优先，且原生 Swift 实现 WYSIWYG 过于复杂、可靠性存疑。这是一个清晰的取舍，它牺牲了即时渲染的直观性，换来了编辑器的稳定性和代码库的可维护性。分屏模式支持 60fps 双向滚动同步，快捷键 ⌘\ 可快速切换，说明团队在细节体验上做了投入。
安装与存储路径配置：三种方式，一个核心步骤
安装途径有三种：Mac App Store（付费）、Homebrew 命令 brew install --cask miaoyan、GitHub Releases 下载 DMG，三者的代码库相同。安装后最关键的一步是设置存储路径：在 iCloud Drive、桌面云盘文件夹或任意位置创建 MiaoYan 文件夹，然后打开偏好设置（⌘,）指定该路径。MiaoYan 在切换文件夹前会验证读写权限，如果文件夹不可用，当前路径保持不变。这个设计避免了误操作导致数据丢失，但也意味着你必须先手动创建文件夹，否则无法完成设置。
CLI 工具：终端操作的实用补充
MiaoYan 提供了一个命令行接口，通过 curl 脚本安装，支持 miao open、miao new、miao search、miao list、miao cat 等命令。这些命令覆盖了打开笔记、新建、搜索、列出目录和打印内容的基本操作。对于习惯终端的用户，这比打开 GUI 更快，尤其是 miao search 可以直接在终端里检索笔记内容。不过，CLI 目前只支持这些有限操作，没有删除或重命名命令，说明它定位为快速入口而非完整管理工具。脚本安装方式需要你信任该 URL 的来源，这是使用前需要自行判断的风险点。
同步机制：依赖外部云盘，而非内置服务
MiaoYan 不内置同步，它依赖 iCloud Drive、Nutstore、Dropbox 等云盘客户端来同步文件夹。具体做法是：在 Mac 上把 MiaoYan 文件夹放在云盘同步目录内，然后在偏好设置中指向它；在 iPhone 上，从系统文件应用选择同一个云盘文件夹。这里有一个实际限制：如果云盘服务不在文件应用中暴露可写文件夹，你就无法在 iPhone 上使用，只能改用 iCloud Drive 或在提供商应用内先设为离线可用。这个设计把同步的复杂性外包给了第三方，好处是代码更简单，坏处是同步失败时你无法从 MiaoYan 内部排查问题。
功能亮点与扩展：双向链接、LaTeX、Mermaid 与 PPT 模式
MiaoYan 支持 wikilink 双向链接、LaTeX 数学公式、Mermaid 图表，以及基于 reveal.js 的 PPT 演示模式，用 --- 分隔幻灯片。这些功能超出了普通笔记应用的范畴，尤其是 PPT 模式，让 Markdown 文件可以直接转化为演示文稿，省去了导出步骤。它还提供版本历史、键盘快捷键和自动格式化，后者基于 Prettier 库。文档中附带了完整的 Markdown 语法指南和 PPT 指南，并提供了一个 Agent Skill，可通过 npx skills add tw93/MiaoYan/skills/miaoyan -g 安装，用于教授 AI 代理 MiaoYan 的语法和工作流。这显示出项目对自动化工作流的重视。
局限性与替代方案：为什么不是所有人的选择
MiaoYan 的局限很明显：它没有 WYSIWYG，如果你习惯了 Typora 的即时渲染，分屏模式会显得多余。它的同步完全依赖外部云盘，如果你不想用 iCloud 或 Nutstore，就得自己找方案，而且云盘的文件锁定冲突可能导致笔记版本分裂。此外，Mac App Store 版本是付费的，虽然 Homebrew 和 GitHub Releases 可能免费，但 README 没有明确说明后两者的价格，这需要你自行确认。替代方案方面，Typora 是直接对手，它采用 WYSIWYG 编辑，但底层是 Electron，资源占用更高。FSNotes（glushchenko/fsnotes）是 MiaoYan 的架构参考，同样基于纯文本文件，但它是开源且免费的，提供了更多自定义选项。FSNotes 的同步策略与 MiaoYan 类似，也依赖外部文件夹，但它的编辑体验更接近传统笔记应用。
维护与许可证：活跃开发与 MIT 许可
仓库显示默认分支为 main，最近推送时间为 2026 年 8 月，最新版本 V4.2.0 于同一天发布，此前还有 V4.1.0 和 V4.0.0，更新频率约为每月一次。这表明项目处于活跃维护状态，但注意这些版本号以怪物猎人怪物命名（Zinogre、Aegis、Valstrax），可能只是版本代号，不代表功能增量。许可证为 MIT，意味着你可以自由使用、修改和分发代码，甚至用于商业项目，但需保留版权声明。项目结构参考了 FSNotes，Markdown 解析使用 swift-cmark-gfm，格式化使用 Prettier，这些依赖的许可证需要在使用时一并考虑。对于企业用户，MIT 许可降低了法律风险，但你需要自己跟踪上游依赖的更新。
编辑结论
MiaoYan 适合那些坚持纯 Markdown 编辑、反感 Electron 应用内存占用、且愿意自己管理云盘同步的 macOS 用户。它不适合需要 WYSIWYG 即时渲染、或依赖内置 WebDAV 同步的笔记重度用户。在采用前，先确认你的云盘客户端（如 Nutstore）能在系统文件应用中暴露可写文件夹，否则 iPhone 端无法正常选择存储路径。同时验证 MiaoYan 的文件夹读写检查机制是否与你当前的云盘冲突，避免切换存储路径失败。
社区笔记