去年整理手机存储的时候我才突然意识到自己过去六七年攒下的笔记已经散落在四个完全不同的工具里有云笔记里排版精美的页面有本地文本文件有备忘录里的随手记录还有几个被永久关闭的旧产品里导出来的残缺快照。每一次工具停运或改版都意味着一次伤筋动骨的迁移。当时我做了个决定把所有笔记统一转成 Markdown整个放进一个私有 Git 仓库然后花两周时间写了一个专门的 App 来管理这个仓库。这套方案看上去很“硬核”但它一次性解决了我最在意的三件事任何一条笔记都有完整版本历史所有数据都是以普通文件的形式存在随时可以整套迁走手机、平板、电脑之间的同步完全依赖 Git 的 push/pull 机制不押注在任何一家笔记厂商的同步云上。这篇文章我会从选型逻辑、App 架构、Git 在移动端的坑、搜索与双链实现到真实故障排查完整复述一遍。如果你也和“笔记散落、导出困难、历史版本找不回”这些问题缠斗过这篇东西应该能给你不少有用的参考。1. 为什么我最后把笔记押注在 Git 而不是哪家云笔记上1.1 笔记软件让我崩溃的三个问题先说说我从前踩过的坑。第一个问题是同步是个黑盒。云笔记的“同步成功”状态对我来说永远是薛定谔的猫有时候手机端改了半天的内容打开电脑端还是旧版本过了一会儿又突然被覆盖掉。更离谱的一次某个云笔记产品在后台调整数据结构第二天我打开 App全部笔记的更新时间被批量刷新了一遍我当时心里就咯噔一下立刻意识到自己的数据其实完全不受控。第二个问题是版本历史形同虚设。多数笔记软件能提供“历史版本”功能的本来就少即便有通常也只保留最近几次更改而且很多情况下一个笔记被误删后整个恢复流程复杂到让你宁愿重新写一遍。对写长文、做知识管理的人来说这几乎是致命的短板。我写文章经常是三天前的一个思路删掉了三天后发现还是原来的好没有可靠的版本历史就只能吃哑巴亏。第三个问题是导出等于脱层皮。有些工具标榜开放结果导出之后是 HTML、PDF 甚至私有格式有的号称支持 Markdown但图片全部变成一堆失效链接附件路径乱成一锅粥。每搬一次家就丢一批数据长期下来我能明显感觉到所有笔记生态都像是在用“迁移成本”锁定用户。本地双链软件我也试过一阵子。数据确实在本地但很多语法是私有化的渲染效果绑定特定客户端批量操作、自定义脚本、和程序化流程的整合能力也很有限。对我来说它们只是把云端黑盒换成了本地黑盒没有解决根本问题。1.2 Git 作为笔记仓库的三个底层优势我选择 Git 不是图新鲜而是因为它有三个特质和笔记管理几乎完美互补。第一是版本的完整性。Git 里的每次 commit 都是整个仓库的一个快照意味着每一行文字的全部历史状态都可以找回。我今天删掉的段落、昨天改坏的标题、上周加的一段至今没用的想法全在 commit 记录里躺着。配合git diff可以精确到行级看到任何一次改动这对写作型笔记来说是实打实的“后悔药”。第二是纯文本的天然契合性。Markdown 本质就是纯文本而 Git 最擅长处理的就是文本比较和文本合并。Git 对二进制文件并不友好但笔记内容正好几乎全是文字稍微设计一下格式就能完全绕过 Git 的弱点。前端开发这么多年我还真没见过第二种工具能像 Git 这样把文本级 diff、合并、历史快照做到这个精细度的。第三是增量同步效率。虽然每次 commit 相当于一个快照但 Git 在传输对象的时候算的是差异包改一个 10KB 的文本文件推到远程仓库通常只需要传输几百字节。移动网络环境下这个特性让同步体验非常接近云笔记。更别说整个 Git 生态到处都是成熟客户端即便我那个 App 出问题我兜底还有命令行可以继续干活。当然 Git 也不是没有缺点它不自带全文搜索不能直接渲染富文本没有标签和双链表更别提在手机上跑命令行。这些短板恰恰是我写那个 App 的原因——用工程手段给 Git 仓库补上一套知识库该有的体验。1.3 统一笔记格式Markdown front matter 的工程化为了让仓库可被程序稳定处理第一步是把所有历史笔记清洗成统一格式。我的每篇笔记都是单文件 Markdown顶部保留 YAML front matter 存元数据--- title: 用 Git 管理笔记的架构复盘 tags: [git, app, 知识管理] created: 2024-03-10 09:30 updated: 2024-05-16 22:10 status: published --- 正文内容从这里开始……目录结构我也做了严格约定。_inbox负责收集所有快速记录的东西定期整理归档proj下面按项目分子目录life放生活类记录archive放已经不再活跃的旧内容assets单独放笔记引用的图片和附件但后面我会讲资产文件如果管理不好会造成什么灾难。notes/ ├── _inbox/ ├── proj/ │ ├── project-alpha/ │ └── blog-ideas/ ├── life/ ├── archive/ └── assets/文件名统一用20240516-1030-简短slug.md这种带时间戳和语义名的格式好处是排序稳定、搜索友好、几乎不会重名。我还为.gitignore配好了规则把.DS_Store、临时文件、导出缓存全部拒之门外保证仓库里永远只会有真正的笔记内容。2. App 到底在管些什么解析、索引、渲染三层管线2.1 定位不是再做一个 Markdown 编辑器而是仓库前端很多人问我既然用了 Git直接用命令行或者桌面端编辑工具不就好了为什么还要写个 App答案是手机场景下你需要快速看一条笔记、临时记一个灵感、通勤路上翻翻自己的知识库这时候不可能打开终端敲git log。所以这个 App 的定位从来不是“又一个 Markdown 编辑器”而是给手机用户提供一个看得见、搜得到、能编辑、能同步的 Git 仓库前端。它的价值链条很清楚把 Git 仓库在移动端无法直接暴露的那部分能力——比如可视化浏览、全文搜索、标签过滤、双链跳转——全部用界面补上。至于编辑动作最终落地的仍然是一次标准的git commit。这样 App 无论多花哨底层永远是一套你能完全掌控的 Git 仓库。技术上我最后选了 Flutter。原因有三个方面一是 Flutter 的跨平台性让我一份代码同时覆盖 iOS 和 Android二是flutter_markdown生态成熟代码高亮、表格渲染基本开箱即用三是通过插件机制可以轻松对接原生 Git 二进制。个人项目最怕的不是功能做不完而是各端各写一套维护到吐。方案跨平台成本Git 集成难度渲染生态我的结论Flutter一套代码跑移动端和桌面通过预编译 Git 二进制 dugite 实现方案成熟flutter_markdown 很完善最终选择React Native跨平台但原生模块桥接繁琐需要 JSI 桥接调试成本高有可用的 Markdown 库备选Electron桌面端体验好移动端不适用集成容易markdown-it 等非常成熟不适合手机场景原生双端各端各写一套每端都要维护 Git 集成各端单独实现个人项目成本太高2.2 Git 引擎选型和命令封装移动端沙盒环境里不能直接在 shell 里调git所以我需要能把 Git 引入 App 的引擎。我最终用的是dugite这是从 GitHub Desktop 开源项目里拆分出来的 Git 封装库核心思路就是把预编译好的 Git 二进制放进应用包然后通过命令行调用再解析输出结果。选择它而不是isomorphic-git纯 JS 实现是因为前者调用的是完整的原生 Git处理 pull/merge/rebase 这类复杂场景时行为与命令行完全一致几乎不需要踩“我实现了大部分但边界偶有不一样”的坑。工程上我把常用的操作封装成了几个同步函数界面层只管调用FutureSyncResult syncAll() async { await git.pull(); await indexer.update(); } Futurevoid commitAll({String? customMessage}) async { await git.add([-A]); await git.commit(customMessage ?? update from app); await git.push(); }这里面值得注意的几个细节第一pull和push必须带超时和重试逻辑移动网络随时可能中断第二add -A意味着把当前所有改动全部纳入一次提交适合笔记这种轻量变更场景第三如果拉取后发现文件变化立即触发索引更新保证搜索结果是实时的。整套流程就像给 App 装了一个“自动 commit 的编辑器”心脏。2.3 三层管线的落地结构App 内部我严格分成了解析、索引、渲染三层。解析层负责读文件把 Markdown 正文和 YAML front matter 分离把 tags、title、created、updated 这些字段转为结构化对象。索引层把这些结构化数据写入本地 SQLite 全文索引详情第四章展开。渲染层则负责把 Markdown 源码渲染成可阅读的页面同时支持代码高亮、任务列表、表格、数学公式。在实现管线前我犯过一个错误刚开始把“解析文件”和“更新索引”做成了同步操作每次打开笔记都要重新解析一遍五百篇笔记之后明显感到卡顿。后来改成只在文件变更或 commit 拉取后触发增量更新平时直接读取缓存整个体验立刻变得丝滑。这个设计思路对后来加搜索、双链等功能帮助非常大。3. 手机上跑 Git 的实操细节认证、同步与冲突处理3.1 远程仓库与登录凭证怎么选远程仓库我用的是自建实例理由很简单数据在我自己的服务上不依赖任何商业平台的策略变动。当然如果你不想折腾用 GitHub 私有仓库也完全可以反正仓库格式是标准 Git以后想迁移随时能迁走。登录凭证上我强烈建议用 SSH 密钥而不是 HTTPS 账号密码。HTTPS 方式的 Personal Access Token 会过期过期之后 App 里所有同步全部静默失败排查起来很头大。SSH 用ed25519类型的密钥一次性配置好之后 push/pull 就不再需要任何交互式认证。移动端这把私钥保存在系统安全区里同时我会在电脑上保留一份备份防止手机丢失或重置后什么都找不回来。切记任何情况下都不要把私钥提交进 Git 仓库。3.2 同步时机和频率控制同步机制的节奏非常重要太激进会放大电池和流量的消耗太保守又会让多端协同形同虚设。我的做法是在三个位置触发同步打开 App 时后台执行一次git pull保证看到的是最新内容。下拉列表时强制手动刷新训练肌肉记忆。编辑保存后自动执行一次 commit push保证手机端做的改动立刻出门。连续编辑场景不能每敲一个字就 commit 一次否则仓库会被几百条“auto save”淹没。我给编辑框加了一个防抖机制停止输入五秒才自动提交如果用户主动点了“保存”按钮则立即提交提交信息由用户自己写。这样历史记录既不会稀疏到丢改动也不会噪音刷屏。3.3 冲突处理没有想象的那么恐怖很多人一听“Git 冲突”就头大但笔记场景下冲突概率其实非常低。因为每篇笔记是独立文件多设备同时改同一个文件的概率本来就不高而且 Git 的文本合并是按行计算的多半情况下两个人改的是不同段落合并会自动成功。只有两边改了同一行内容时才会出现真正的冲突。遇到冲突时我的 App 会给出三种处理操作保留本机版本、保留远程版本、两版共存。前两种适合明确知道谁的内容有效的情况最后一种最适合笔记场景——把冲突文件复制成两个文件一份叫xxx.merged.md、一份叫xxx.conflict.md保证任何一方的信息都不会丢。稍后有空再整理。同步策略上我从头到尾都坚持一个原则全部用 merge不用 rebase。因为 rebase 会改写历史在移动端一旦手表不同步很容易让仓库状态变得混乱merge 会产生一个合并节点虽然历史不是绝对线性但一切都是可追溯的真实记录。3.4 手机端 / 桌面端协同的日常流程这套方案最舒服的地方就在于桌面端完全不需要配合我写任何额外客户端。我在电脑上写长文时对这个目录直接git clone然后使用自己喜欢的编辑器打开。桌面端任何修改推送到远程仓库后手机上打开 App 自动 pull 就看到了。反过来我在通勤路上用 App 快速记录的想法回家一开电脑就是最新的。实际用下来跨端编辑冲突真的很少倒是因为网络不稳导致 push 失败的情况偶尔出现。遇到这种情况我的 App 会把 commit 留在本地下次有网络时自动补推基本不影响使用。4. 搜索、标签和双链仓库变大后 App 怎么保持好用4.1 全文检索直接上 SQLite FTS5笔记数量一旦冲到几百上千篇靠内存遍历或者 grep 式搜索就已经不可能在手机上丝滑跑起来了。我的方案是直接在 App 里内嵌一个 SQLite 数据库利用 FTS5 虚拟表做全文索引。CREATE VIRTUAL TABLE notes_fts USING fts5( title, content, tags, tokenizeunicode61 );每条笔记在解析后把标题、正文、tags 写进这条虚拟表里。搜索时可以把一个关键词的匹配范围覆盖到全部字段响应时间基本在几十毫秒级别。对比一下之前在文件系统层面暴力搜索一千篇笔记动辄两三秒偶尔还会转圈圈这个体验差异是碾压级的。中文分词是这里最容易踩的坑。FTS5 内置的unicode61tokenizer 对中文的处理基本是逐字切分搜索“笔记”时相当于搜“笔”和“记”的组合噪声会偏大。我在做索引的时候对内容做了一层轻度分词处理按标点和常见切词规则拆成词组后用空格连接再写入索引。这个方案不需要引入重型分词库在移动端的性能开销也可控。如果你对精度有更高要求可以换成 jieba 分词但一定要做缓存否则每次索引更新的耗时非常可观。4.2 标签、双链这些“高级功能”的极简实现标签系统不需要什么图数据库我在 front matter 里存一个 tags 数组就够了。列表页直接按 tag 分组展示搜索时也可以指定 tag 过滤逻辑简单可靠。双链表怎么做渲染 Markdown 时用正则把[[笔记文件名]]这种语法匹配出来转换成 App 内部路由跳转点击就打开对应笔记。反向链接列表则是用 SQL 查一下有哪篇笔记的内容里包含当前文件名一次性列出来。SELECT title FROM notes_fts WHERE content LIKE %[[xxx]]%;以我目前两千篇笔记的规模这套实现已经足够应对完全没有必要为了“知识图谱”的噱头上重型关系数据库。真正值钱的是内容本身而不是用什么高端方式把内容连起来。4.3 渲染层和移动端交互的几个细节移动端渲染 Markdown 时最难处理的是数学公式和代码块。数学公式需要接入渲染数学引擎在长文里还要保证滚动性能代码块则要按语言做高亮。这些细节如果处理不好知识型笔记的阅读体验会大打折扣。我自己调试了很久结论是宁可砍掉 20% 花哨排版也要保证 80% 的主流程流畅。阅读列表的交互我最后采用了“最近更新 标签筛选 全文搜索”三驾马车树形目录只保留在文件夹浏览页里。因为移动端屏幕太窄用户绝大多数时间并不需要一级级展开目录他们需要的是“输入关键词就能找到目标”以及“看到最近在改什么”。快速记录是移动端最重要的入口我还做了系统快捷方式从桌面或分享面板可以直接呼出“随手记”页面内容默认扔进_inbox开头再加一条时间戳。这样即使在地铁上只有三十秒也能把一个想法低成本地捕获到仓库里。5. 让我头疼过的几个真实故障与修复过程5.1 仓库膨胀到 1.2GB二进制文件是如何混进去的大概在项目跑到第三个月的时候我偶然发现克隆仓库的速度越来越慢手机端同步也开始频繁因为超时中断。我跑了一下仓库体积统计git count-objects -vH结果让我吓一跳仓库对象总体积已经超过 1.2GB。我当时的习惯是给部分笔记配截图然后顺手丢进了assets/这就埋下了灾难的种子。Git 保存的是每一次 commit 的快照如果修改一个 5MB 的 PDF 并提交十次仓库里就躺着 50MB 的冗余对象而且永远不会自动消失。我把仓库里最大的几十个文件抓出来看git rev-list --objects --all | git cat-file --batch-check%(objecttype) %(objectname) %(objectsize) %(rest) | awk /^blob/ {print $3, $4} | sort -n | tail -10结果不出所料清一色是截图和 PDF。最后我用git filter-repo把这些大文件的旧历史从整个仓库里彻底抹掉然后强制推送全部分支再执行了一次彻底的垃圾回收git filter-repo --invert-paths --path-glob assets/2024*.pdf git push origin --force --all git gc --prunenow --aggressive这套操作之后仓库体积直接回落到 30MB 左右。血的教训是Git 仓库只应该承载文本大文件一律放对象存储或普通网盘正文里存链接就行。如果你确实需要给渲染资源做版本管理用 Git LFS 也要注意自己的配额成本。5.2 中文文件名变成转义序列有一段时间我在手机上打开仓库列表看到大量文件名显示成\346\265\213\350\257\225这种格式整个人都不好了。这个问题的原因是 Git 默认对非 ASCII 路径做了转义处理它只是为了显示安全并不是文件真的损坏了。解决办法很简单在 App 的 Git 配置里设置一行git config core.quotepath false之后中文文件名就能正常显示和点击。不过这个坑让我意识到文件名里尽量用拼音或者英文 slug 会更省心尤其是未来如果要在多端之间做复杂合并一个可读的文件名能帮你减少大量判断成本。5.3 自动提交刷出大量噪音历史很早之前我把自动 commit 的逻辑做得太激进停止输入五秒就提交一次结果一个下午产生了几十条update from app的提交记录。几天之后看历史日志满屏都是毫无信息的自动保存点手动去找某个有意义的变更完全找不到。我重新设计了提交策略日常编辑的自动提交会集中写到一个叫autosave的分支上每天定时把autosave合并回主分支并生成一条像样的汇总提交信息里包含当天改动的文件列表。偶尔哪天做了重要改动我会手动在主分支上创建带有明确标题的里程碑提交。这样既不丢过程又能时刻保持主分支历史的干净和可读性。这种双轨提交策略也是我在这段经历里最满意的一个设计。5.4 换手机之后仓库差点找不回来有一次我换了新手机重置了旧设备这时才发现一个问题App 里的 SSH 私钥和本地仓库都没有办法跨设备自动迁移。新手机上虽然装了 App但打开后什么都拉不下来对着空仓库首页愣了好一会儿。幸好我在电脑上备份了私钥并且远程仓库一直保持着完整数据所以我重新走了一整套恢复流程新手机导入私钥、重新克隆仓库、让 App 重建本地索引几分钟之后全部笔记都回来了。这让我想明白了一个非常关键的原则这个方案里唯一的事实来源永远是远程仓库任何本地缓存和设备上的状态都只是临时副本。只要远程仓库和密钥备份没有丢换任何新设备都只是“重新同步”的问题不存在数据被绑定死在某个 App 或某台设备上的情况。现在这个仓库已经稳定跑了大半年里面有大约两千篇笔记、四千多条 commit手机端和桌面端每天交替使用。我更确信了一件事知识管理工具的核心价值并不在于有多少花哨的视图而在于底层数据是否真正属于你、是否可以被任意工具打开、是否从不丢失历史。自己动手写 App 也并没那么神秘本质上就是把 Git 仓库包一层更好用的壳。如果你也想复刻这套方案我给的建议是不要急着把十年的旧笔记一次性迁入。先建一个干净的仓库跑一个月的日常记录让同步节奏、目录规范、搜索体验都稳定下来再逐步把旧内容搬进去。整个过程比我预想中成本低得多而收益是长期且持续的。
用Git和Markdown打造私有笔记系统：从自建App到多端同步
去年整理手机存储的时候我才突然意识到自己过去六七年攒下的笔记已经散落在四个完全不同的工具里有云笔记里排版精美的页面有本地文本文件有备忘录里的随手记录还有几个被永久关闭的旧产品里导出来的残缺快照。每一次工具停运或改版都意味着一次伤筋动骨的迁移。当时我做了个决定把所有笔记统一转成 Markdown整个放进一个私有 Git 仓库然后花两周时间写了一个专门的 App 来管理这个仓库。这套方案看上去很“硬核”但它一次性解决了我最在意的三件事任何一条笔记都有完整版本历史所有数据都是以普通文件的形式存在随时可以整套迁走手机、平板、电脑之间的同步完全依赖 Git 的 push/pull 机制不押注在任何一家笔记厂商的同步云上。这篇文章我会从选型逻辑、App 架构、Git 在移动端的坑、搜索与双链实现到真实故障排查完整复述一遍。如果你也和“笔记散落、导出困难、历史版本找不回”这些问题缠斗过这篇东西应该能给你不少有用的参考。1. 为什么我最后把笔记押注在 Git 而不是哪家云笔记上1.1 笔记软件让我崩溃的三个问题先说说我从前踩过的坑。第一个问题是同步是个黑盒。云笔记的“同步成功”状态对我来说永远是薛定谔的猫有时候手机端改了半天的内容打开电脑端还是旧版本过了一会儿又突然被覆盖掉。更离谱的一次某个云笔记产品在后台调整数据结构第二天我打开 App全部笔记的更新时间被批量刷新了一遍我当时心里就咯噔一下立刻意识到自己的数据其实完全不受控。第二个问题是版本历史形同虚设。多数笔记软件能提供“历史版本”功能的本来就少即便有通常也只保留最近几次更改而且很多情况下一个笔记被误删后整个恢复流程复杂到让你宁愿重新写一遍。对写长文、做知识管理的人来说这几乎是致命的短板。我写文章经常是三天前的一个思路删掉了三天后发现还是原来的好没有可靠的版本历史就只能吃哑巴亏。第三个问题是导出等于脱层皮。有些工具标榜开放结果导出之后是 HTML、PDF 甚至私有格式有的号称支持 Markdown但图片全部变成一堆失效链接附件路径乱成一锅粥。每搬一次家就丢一批数据长期下来我能明显感觉到所有笔记生态都像是在用“迁移成本”锁定用户。本地双链软件我也试过一阵子。数据确实在本地但很多语法是私有化的渲染效果绑定特定客户端批量操作、自定义脚本、和程序化流程的整合能力也很有限。对我来说它们只是把云端黑盒换成了本地黑盒没有解决根本问题。1.2 Git 作为笔记仓库的三个底层优势我选择 Git 不是图新鲜而是因为它有三个特质和笔记管理几乎完美互补。第一是版本的完整性。Git 里的每次 commit 都是整个仓库的一个快照意味着每一行文字的全部历史状态都可以找回。我今天删掉的段落、昨天改坏的标题、上周加的一段至今没用的想法全在 commit 记录里躺着。配合git diff可以精确到行级看到任何一次改动这对写作型笔记来说是实打实的“后悔药”。第二是纯文本的天然契合性。Markdown 本质就是纯文本而 Git 最擅长处理的就是文本比较和文本合并。Git 对二进制文件并不友好但笔记内容正好几乎全是文字稍微设计一下格式就能完全绕过 Git 的弱点。前端开发这么多年我还真没见过第二种工具能像 Git 这样把文本级 diff、合并、历史快照做到这个精细度的。第三是增量同步效率。虽然每次 commit 相当于一个快照但 Git 在传输对象的时候算的是差异包改一个 10KB 的文本文件推到远程仓库通常只需要传输几百字节。移动网络环境下这个特性让同步体验非常接近云笔记。更别说整个 Git 生态到处都是成熟客户端即便我那个 App 出问题我兜底还有命令行可以继续干活。当然 Git 也不是没有缺点它不自带全文搜索不能直接渲染富文本没有标签和双链表更别提在手机上跑命令行。这些短板恰恰是我写那个 App 的原因——用工程手段给 Git 仓库补上一套知识库该有的体验。1.3 统一笔记格式Markdown front matter 的工程化为了让仓库可被程序稳定处理第一步是把所有历史笔记清洗成统一格式。我的每篇笔记都是单文件 Markdown顶部保留 YAML front matter 存元数据--- title: 用 Git 管理笔记的架构复盘 tags: [git, app, 知识管理] created: 2024-03-10 09:30 updated: 2024-05-16 22:10 status: published --- 正文内容从这里开始……目录结构我也做了严格约定。_inbox负责收集所有快速记录的东西定期整理归档proj下面按项目分子目录life放生活类记录archive放已经不再活跃的旧内容assets单独放笔记引用的图片和附件但后面我会讲资产文件如果管理不好会造成什么灾难。notes/ ├── _inbox/ ├── proj/ │ ├── project-alpha/ │ └── blog-ideas/ ├── life/ ├── archive/ └── assets/文件名统一用20240516-1030-简短slug.md这种带时间戳和语义名的格式好处是排序稳定、搜索友好、几乎不会重名。我还为.gitignore配好了规则把.DS_Store、临时文件、导出缓存全部拒之门外保证仓库里永远只会有真正的笔记内容。2. App 到底在管些什么解析、索引、渲染三层管线2.1 定位不是再做一个 Markdown 编辑器而是仓库前端很多人问我既然用了 Git直接用命令行或者桌面端编辑工具不就好了为什么还要写个 App答案是手机场景下你需要快速看一条笔记、临时记一个灵感、通勤路上翻翻自己的知识库这时候不可能打开终端敲git log。所以这个 App 的定位从来不是“又一个 Markdown 编辑器”而是给手机用户提供一个看得见、搜得到、能编辑、能同步的 Git 仓库前端。它的价值链条很清楚把 Git 仓库在移动端无法直接暴露的那部分能力——比如可视化浏览、全文搜索、标签过滤、双链跳转——全部用界面补上。至于编辑动作最终落地的仍然是一次标准的git commit。这样 App 无论多花哨底层永远是一套你能完全掌控的 Git 仓库。技术上我最后选了 Flutter。原因有三个方面一是 Flutter 的跨平台性让我一份代码同时覆盖 iOS 和 Android二是flutter_markdown生态成熟代码高亮、表格渲染基本开箱即用三是通过插件机制可以轻松对接原生 Git 二进制。个人项目最怕的不是功能做不完而是各端各写一套维护到吐。方案跨平台成本Git 集成难度渲染生态我的结论Flutter一套代码跑移动端和桌面通过预编译 Git 二进制 dugite 实现方案成熟flutter_markdown 很完善最终选择React Native跨平台但原生模块桥接繁琐需要 JSI 桥接调试成本高有可用的 Markdown 库备选Electron桌面端体验好移动端不适用集成容易markdown-it 等非常成熟不适合手机场景原生双端各端各写一套每端都要维护 Git 集成各端单独实现个人项目成本太高2.2 Git 引擎选型和命令封装移动端沙盒环境里不能直接在 shell 里调git所以我需要能把 Git 引入 App 的引擎。我最终用的是dugite这是从 GitHub Desktop 开源项目里拆分出来的 Git 封装库核心思路就是把预编译好的 Git 二进制放进应用包然后通过命令行调用再解析输出结果。选择它而不是isomorphic-git纯 JS 实现是因为前者调用的是完整的原生 Git处理 pull/merge/rebase 这类复杂场景时行为与命令行完全一致几乎不需要踩“我实现了大部分但边界偶有不一样”的坑。工程上我把常用的操作封装成了几个同步函数界面层只管调用FutureSyncResult syncAll() async { await git.pull(); await indexer.update(); } Futurevoid commitAll({String? customMessage}) async { await git.add([-A]); await git.commit(customMessage ?? update from app); await git.push(); }这里面值得注意的几个细节第一pull和push必须带超时和重试逻辑移动网络随时可能中断第二add -A意味着把当前所有改动全部纳入一次提交适合笔记这种轻量变更场景第三如果拉取后发现文件变化立即触发索引更新保证搜索结果是实时的。整套流程就像给 App 装了一个“自动 commit 的编辑器”心脏。2.3 三层管线的落地结构App 内部我严格分成了解析、索引、渲染三层。解析层负责读文件把 Markdown 正文和 YAML front matter 分离把 tags、title、created、updated 这些字段转为结构化对象。索引层把这些结构化数据写入本地 SQLite 全文索引详情第四章展开。渲染层则负责把 Markdown 源码渲染成可阅读的页面同时支持代码高亮、任务列表、表格、数学公式。在实现管线前我犯过一个错误刚开始把“解析文件”和“更新索引”做成了同步操作每次打开笔记都要重新解析一遍五百篇笔记之后明显感到卡顿。后来改成只在文件变更或 commit 拉取后触发增量更新平时直接读取缓存整个体验立刻变得丝滑。这个设计思路对后来加搜索、双链等功能帮助非常大。3. 手机上跑 Git 的实操细节认证、同步与冲突处理3.1 远程仓库与登录凭证怎么选远程仓库我用的是自建实例理由很简单数据在我自己的服务上不依赖任何商业平台的策略变动。当然如果你不想折腾用 GitHub 私有仓库也完全可以反正仓库格式是标准 Git以后想迁移随时能迁走。登录凭证上我强烈建议用 SSH 密钥而不是 HTTPS 账号密码。HTTPS 方式的 Personal Access Token 会过期过期之后 App 里所有同步全部静默失败排查起来很头大。SSH 用ed25519类型的密钥一次性配置好之后 push/pull 就不再需要任何交互式认证。移动端这把私钥保存在系统安全区里同时我会在电脑上保留一份备份防止手机丢失或重置后什么都找不回来。切记任何情况下都不要把私钥提交进 Git 仓库。3.2 同步时机和频率控制同步机制的节奏非常重要太激进会放大电池和流量的消耗太保守又会让多端协同形同虚设。我的做法是在三个位置触发同步打开 App 时后台执行一次git pull保证看到的是最新内容。下拉列表时强制手动刷新训练肌肉记忆。编辑保存后自动执行一次 commit push保证手机端做的改动立刻出门。连续编辑场景不能每敲一个字就 commit 一次否则仓库会被几百条“auto save”淹没。我给编辑框加了一个防抖机制停止输入五秒才自动提交如果用户主动点了“保存”按钮则立即提交提交信息由用户自己写。这样历史记录既不会稀疏到丢改动也不会噪音刷屏。3.3 冲突处理没有想象的那么恐怖很多人一听“Git 冲突”就头大但笔记场景下冲突概率其实非常低。因为每篇笔记是独立文件多设备同时改同一个文件的概率本来就不高而且 Git 的文本合并是按行计算的多半情况下两个人改的是不同段落合并会自动成功。只有两边改了同一行内容时才会出现真正的冲突。遇到冲突时我的 App 会给出三种处理操作保留本机版本、保留远程版本、两版共存。前两种适合明确知道谁的内容有效的情况最后一种最适合笔记场景——把冲突文件复制成两个文件一份叫xxx.merged.md、一份叫xxx.conflict.md保证任何一方的信息都不会丢。稍后有空再整理。同步策略上我从头到尾都坚持一个原则全部用 merge不用 rebase。因为 rebase 会改写历史在移动端一旦手表不同步很容易让仓库状态变得混乱merge 会产生一个合并节点虽然历史不是绝对线性但一切都是可追溯的真实记录。3.4 手机端 / 桌面端协同的日常流程这套方案最舒服的地方就在于桌面端完全不需要配合我写任何额外客户端。我在电脑上写长文时对这个目录直接git clone然后使用自己喜欢的编辑器打开。桌面端任何修改推送到远程仓库后手机上打开 App 自动 pull 就看到了。反过来我在通勤路上用 App 快速记录的想法回家一开电脑就是最新的。实际用下来跨端编辑冲突真的很少倒是因为网络不稳导致 push 失败的情况偶尔出现。遇到这种情况我的 App 会把 commit 留在本地下次有网络时自动补推基本不影响使用。4. 搜索、标签和双链仓库变大后 App 怎么保持好用4.1 全文检索直接上 SQLite FTS5笔记数量一旦冲到几百上千篇靠内存遍历或者 grep 式搜索就已经不可能在手机上丝滑跑起来了。我的方案是直接在 App 里内嵌一个 SQLite 数据库利用 FTS5 虚拟表做全文索引。CREATE VIRTUAL TABLE notes_fts USING fts5( title, content, tags, tokenizeunicode61 );每条笔记在解析后把标题、正文、tags 写进这条虚拟表里。搜索时可以把一个关键词的匹配范围覆盖到全部字段响应时间基本在几十毫秒级别。对比一下之前在文件系统层面暴力搜索一千篇笔记动辄两三秒偶尔还会转圈圈这个体验差异是碾压级的。中文分词是这里最容易踩的坑。FTS5 内置的unicode61tokenizer 对中文的处理基本是逐字切分搜索“笔记”时相当于搜“笔”和“记”的组合噪声会偏大。我在做索引的时候对内容做了一层轻度分词处理按标点和常见切词规则拆成词组后用空格连接再写入索引。这个方案不需要引入重型分词库在移动端的性能开销也可控。如果你对精度有更高要求可以换成 jieba 分词但一定要做缓存否则每次索引更新的耗时非常可观。4.2 标签、双链这些“高级功能”的极简实现标签系统不需要什么图数据库我在 front matter 里存一个 tags 数组就够了。列表页直接按 tag 分组展示搜索时也可以指定 tag 过滤逻辑简单可靠。双链表怎么做渲染 Markdown 时用正则把[[笔记文件名]]这种语法匹配出来转换成 App 内部路由跳转点击就打开对应笔记。反向链接列表则是用 SQL 查一下有哪篇笔记的内容里包含当前文件名一次性列出来。SELECT title FROM notes_fts WHERE content LIKE %[[xxx]]%;以我目前两千篇笔记的规模这套实现已经足够应对完全没有必要为了“知识图谱”的噱头上重型关系数据库。真正值钱的是内容本身而不是用什么高端方式把内容连起来。4.3 渲染层和移动端交互的几个细节移动端渲染 Markdown 时最难处理的是数学公式和代码块。数学公式需要接入渲染数学引擎在长文里还要保证滚动性能代码块则要按语言做高亮。这些细节如果处理不好知识型笔记的阅读体验会大打折扣。我自己调试了很久结论是宁可砍掉 20% 花哨排版也要保证 80% 的主流程流畅。阅读列表的交互我最后采用了“最近更新 标签筛选 全文搜索”三驾马车树形目录只保留在文件夹浏览页里。因为移动端屏幕太窄用户绝大多数时间并不需要一级级展开目录他们需要的是“输入关键词就能找到目标”以及“看到最近在改什么”。快速记录是移动端最重要的入口我还做了系统快捷方式从桌面或分享面板可以直接呼出“随手记”页面内容默认扔进_inbox开头再加一条时间戳。这样即使在地铁上只有三十秒也能把一个想法低成本地捕获到仓库里。5. 让我头疼过的几个真实故障与修复过程5.1 仓库膨胀到 1.2GB二进制文件是如何混进去的大概在项目跑到第三个月的时候我偶然发现克隆仓库的速度越来越慢手机端同步也开始频繁因为超时中断。我跑了一下仓库体积统计git count-objects -vH结果让我吓一跳仓库对象总体积已经超过 1.2GB。我当时的习惯是给部分笔记配截图然后顺手丢进了assets/这就埋下了灾难的种子。Git 保存的是每一次 commit 的快照如果修改一个 5MB 的 PDF 并提交十次仓库里就躺着 50MB 的冗余对象而且永远不会自动消失。我把仓库里最大的几十个文件抓出来看git rev-list --objects --all | git cat-file --batch-check%(objecttype) %(objectname) %(objectsize) %(rest) | awk /^blob/ {print $3, $4} | sort -n | tail -10结果不出所料清一色是截图和 PDF。最后我用git filter-repo把这些大文件的旧历史从整个仓库里彻底抹掉然后强制推送全部分支再执行了一次彻底的垃圾回收git filter-repo --invert-paths --path-glob assets/2024*.pdf git push origin --force --all git gc --prunenow --aggressive这套操作之后仓库体积直接回落到 30MB 左右。血的教训是Git 仓库只应该承载文本大文件一律放对象存储或普通网盘正文里存链接就行。如果你确实需要给渲染资源做版本管理用 Git LFS 也要注意自己的配额成本。5.2 中文文件名变成转义序列有一段时间我在手机上打开仓库列表看到大量文件名显示成\346\265\213\350\257\225这种格式整个人都不好了。这个问题的原因是 Git 默认对非 ASCII 路径做了转义处理它只是为了显示安全并不是文件真的损坏了。解决办法很简单在 App 的 Git 配置里设置一行git config core.quotepath false之后中文文件名就能正常显示和点击。不过这个坑让我意识到文件名里尽量用拼音或者英文 slug 会更省心尤其是未来如果要在多端之间做复杂合并一个可读的文件名能帮你减少大量判断成本。5.3 自动提交刷出大量噪音历史很早之前我把自动 commit 的逻辑做得太激进停止输入五秒就提交一次结果一个下午产生了几十条update from app的提交记录。几天之后看历史日志满屏都是毫无信息的自动保存点手动去找某个有意义的变更完全找不到。我重新设计了提交策略日常编辑的自动提交会集中写到一个叫autosave的分支上每天定时把autosave合并回主分支并生成一条像样的汇总提交信息里包含当天改动的文件列表。偶尔哪天做了重要改动我会手动在主分支上创建带有明确标题的里程碑提交。这样既不丢过程又能时刻保持主分支历史的干净和可读性。这种双轨提交策略也是我在这段经历里最满意的一个设计。5.4 换手机之后仓库差点找不回来有一次我换了新手机重置了旧设备这时才发现一个问题App 里的 SSH 私钥和本地仓库都没有办法跨设备自动迁移。新手机上虽然装了 App但打开后什么都拉不下来对着空仓库首页愣了好一会儿。幸好我在电脑上备份了私钥并且远程仓库一直保持着完整数据所以我重新走了一整套恢复流程新手机导入私钥、重新克隆仓库、让 App 重建本地索引几分钟之后全部笔记都回来了。这让我想明白了一个非常关键的原则这个方案里唯一的事实来源永远是远程仓库任何本地缓存和设备上的状态都只是临时副本。只要远程仓库和密钥备份没有丢换任何新设备都只是“重新同步”的问题不存在数据被绑定死在某个 App 或某台设备上的情况。现在这个仓库已经稳定跑了大半年里面有大约两千篇笔记、四千多条 commit手机端和桌面端每天交替使用。我更确信了一件事知识管理工具的核心价值并不在于有多少花哨的视图而在于底层数据是否真正属于你、是否可以被任意工具打开、是否从不丢失历史。自己动手写 App 也并没那么神秘本质上就是把 Git 仓库包一层更好用的壳。如果你也想复刻这套方案我给的建议是不要急着把十年的旧笔记一次性迁入。先建一个干净的仓库跑一个月的日常记录让同步节奏、目录规范、搜索体验都稳定下来再逐步把旧内容搬进去。整个过程比我预想中成本低得多而收益是长期且持续的。