本地优先笔记数据层设计：SQLite元数据与附件内容寻址实践

做本地优先的笔记应用，很多开发者的第一反应是把 Markdown 文件往文件夹里一扔，觉得文件在本地就算万事大吉。可你一旦把附件、标签、全文检索和跨设备同步加进来，问题立刻变味——你面对的已经不是“写文件”，而是一套迷你持久化系统。我手头这个本地优先笔记项目就是在这一步被卡了很久，核心数据方案用 SQLite 做元数据存储，附件文件采用空间隔离加内容寻址的方式管理。整套做下来，数据层才算真正“不裸奔”。

这篇文章就把这套方案完整拆开讲。包括为什么在本地优先场景里 SQLite 依然是性价比最高的选择，附件为什么不能直接丢在一个目录里，哈希命名的内容寻址到底解决了什么问题，以及 Windows 环境下日常开发怎么选工具、怎么排查 SQLite 相关问题。内容都是我自己实际敲过、跑过、踩出坑之后整理出来的经验，适合正在做本地存储类工具的开发者参考。

1. 本地优先笔记应用，数据层设计的整体思路

1.1 本地优先架构下，什么才是好的数据方案

本地优先（local-first）的核心特征是：用户的全部数据默认落在本地，云服务只是可选的同步通道，而不是数据的主副本。这个架构方向一旦定下来，数据层设计就必须围绕“本地可靠”来展开，而不是先想着怎么把数据推到服务器上。

这就带来三个问题需要解决。第一，笔记正文这类文本数据放哪，既要有结构化查询能力，又要方便以后做全文检索；第二，图片、PDF、音频这类二进制附件放哪，放数据库里还是放文件系统；第三，笔记和附件的关系怎么维护，增删改查时如何保持一致性。三个问题看着独立，实际是同一个设计决策的延伸。

我的结论很直接：用 SQLite 管理结构化元数据，正文文本也进 SQLite，附件文件放文件系统。数据库里只存附件地址、哈希值、大小、MIME 类型这些元信息，真正的二进制内容不塞进 BLOB 字段。这样数据库文件保持轻量，附件读写走文件系统天然的高性能路径，备份时也可以对“数据库”和“附件目录”分别制定策略。

这个方案最核心的优点在于三件事可以同时成立：SQLite 让笔记数据具备完整的 SQL 能力，本地文件让附件不需要被序列化/反序列化，数据库和附件之间通过哈希值关联，又为后面做去重和一致性校验留了口子。

1.2 为什么不直接在纯文本文件里硬扛

有一种更“朴素”的做法是笔记直接用 Markdown 文件存，附件散落在笔记同目录。我早期也试过，能跑，但到后面很痛苦。

最大的问题是没有事务支持。用户复制一段内容、插入一张图片、修改一个标签，这其实是多步操作。如果用纯文件方案，要么自己写一个文件锁来模拟事务，要么干脆接受“写到一半断电，文件损坏”的风险。第二个问题是关联查询极不方便。笔记和标签是多对多关系，笔记和附件是一对多关系，用文件夹来体现这些关系会很快变成一场灾难——你只能在命名规则上想办法，比如 note-001.md、note-001-attach-001.png，一旦数量上去，遍历和匹配的速度和复杂度都不可控。

还有并发问题。笔记应用现在基本都支持多窗口，两个窗口同时操作同一篇笔记的正文，纯文件方案很难做好合并。SQLite 的行级锁和事务在这里帮了大忙。

所以纯文件方案适合纯手动的个人 Markdown 仓库，不适合作为笔记应用的数据内核。用户要的是“打开应用，数据可靠，搜索快，附件不丢”，这些需求天然指向一个小型嵌入式数据库加文件系统的事实标准。

1.3 数据模型拆分：元数据与附件分离

数据模型上，我把系统拆成三个核心部分：笔记主体、附件索引、附件实体。笔记主体存 SQLite，附件实体存文件系统，附件索引表负责把两者串联起来。

笔记表存 ID、UUID、标题、正文内容、创建时间、更新时间、删除标记。UUID 存在的意义在于以后做多端同步时，可以避免自增 ID 在不同设备上产生冲突。附件表存 ID、哈希值、存储路径、MIME 类型、大小、引用计数、创建时间。笔记和附件的关联我通过在附件表里维护 note_id 字段实现，同时保留一个引用计数。

结构上看起来不复杂，但把附件单独拆表非常关键。如果我直接在笔记表里加一个 attachments_json 字段，后续做附件全局去重、统计占用空间、同步时按附件增量传输，都会变得非常绕。独立表加上引用计数，附件服务变成一个小型内容寻址存储系统，后面讲的空间隔离和去重实现起来就顺理成章。