Notesnook monorepo架构深度剖析:13个核心包如何撑起四端统一的加密笔记应用
Notesnook monorepo架构深度剖析:13个核心包如何撑起四端统一的加密笔记应用
Notesnook 是一款完全开源、端到端加密的笔记应用(Evernote 替代品),使用 XChaCha20-Poly1305 与 Argon2 在设备本地完成加密,坚持"零知识"原则。它的 Web、桌面、移动端与浏览器剪藏插件共享同一套代码骨架,这套四端统一的秘密就藏在 monorepo(单体仓库)架构里。本文将带你逐层拆解 packages/ 下的 13 个核心包,看懂它们如何像乐高一样拼出一整个加密笔记应用。
🗂️ 一图看懂 monorepo 目录布局
整个仓库分成五大区域,各司其职:
| 目录 | 职责 |
|---|---|
| apps/web | Web 客户端 |
| apps/desktop | 桌面客户端(Electron) |
| apps/mobile | Android / iOS 客户端(React Native) |
| packages/ | 13 个跨平台共享包(核心所在) |
| extensions/web-clipper | 浏览器网页剪藏插件 |
官方 README 中给出了完整的 monorepo 结构表,是阅读本文的最好索引:README.md。
🔐 第一层:加密地基(sodium → crypto)
加密是 Notesnook 的灵魂,所以架构最底层是密码学栈:
@notesnook/sodium(packages/sodium/):libsodium 的封装层,通过 packages/sodium/src/browser.ts 和 packages/sodium/src/node.ts 分别适配浏览器与 Node.js 环境,让同一套加密代码两端都能跑。@notesnook/crypto(packages/crypto/):在 sodium 之上提供更易用的加解密 API,核心类NNCrypto定义在 packages/crypto/src/index.ts,配套还有 packages/crypto/src/encryption.ts、packages/crypto/src/password.ts 等模块。
依赖关系非常克制:crypto 只依赖 sodium,不碰任何 UI 或平台代码——这正是它能被所有端复用的原因。
💡 顺带一提:仓库里的 apps/vericrypt/ 是一个"加密验证器"Web 应用,任何人都可以打开浏览器开发者工具,亲手验证 Notesnook 的端到端加密声明——开源项目对透明度的极致体现。
🧠 第二层:中枢枢纽(core)
@notesnook/core(packages/core/)是整个 monorepo 的心脏,四端共用的"业务内核"都住在这里:
- 数据库与集合:packages/core/src/database/ 定义本地 SQLite/加密数据库,packages/core/src/collections/ 管理笔记、笔记本、标签、提醒等数据模型;
- 同步与账户 API:packages/core/src/api/ 包含 sync/ 增量同步、key-manager.ts 密钥管理、vault.ts 保险库、token-manager.ts 令牌管理等 20 余个模块;
- 对外出口:所有能力统一从 packages/core/src/index.ts 导出,包括数据库入口
Database、备份文件类型BackupFile、提醒时间工具等。
core 仅依赖 intl、logger、crypto 三个基础包,保证了内核的"纯"——不关心自己是跑在浏览器、Electron 还是手机上。
🎨 第三层:UI 三件套(theme / ui / editor)
@notesnook/theme(packages/theme/):Web 与桌面端共用主题引擎,含 packages/theme/src/theme-engine/ 主题引擎与 v1.schema.json 主题校验 schema,支持社区自定义主题;@notesnook/ui(packages/ui/):依赖 theme 的通用 UI 组件;@notesnook/editor(packages/editor/):基于 TipTap/ProseMirror 的富文本编辑器,packages/editor/src/extensions/ 下有 178 个扩展文件(任务列表、数学公式、代码高亮、内链等),packages/editor/src/toolbar/ 则是 45 个工具栏组件;@notesnook/editor-mobile(packages/editor-mobile/):README 自述为"对 editor 的极薄封装",专门为 React Native 适配移动端编辑器。
🧩 横向支撑包:common / logger / intl / streamable-fs / clipper
| 包 | 路径 | 作用 |
|---|---|---|
@notesnook/common |
packages/common/ | 各端共享的工具集(依赖 core) |
@notesnook/logger |
packages/logger/ | 可插拔的轻量日志器 |
@notesnook/intl |
packages/intl/ | 基于 Lingui 的多语言国际化 |
@notesnook/streamable-fs |
packages/streamable-fs/ | 基于 IndexedDB 的可流式文件系统,用于大附件分片读写 |
@notesnook/clipper |
packages/clipper/ | 网页剪藏核心:克隆 DOM、内联样式、截图(见 packages/clipper/src/clone.ts) |
这些包彼此依赖极少,形成"树状"而非"网状"的依赖结构,任何一端升级 UI 都不必动加密内核。
📱 四端如何组装这些积木
通过查看各端 package.json 的依赖,可以画出清晰的组装关系:
- Web(apps/web/):依赖
core、crypto、editor、theme、ui、streamable-fs等最多,功能最全,还内嵌了 Web Clipper 页面; - Desktop(apps/desktop/):渲染层依赖
intl+ui,而系统能力(安全存储 safe-storage、SQLite 加密库、自动更新、托盘与菜单)由 apps/desktop/src/ 的 Electron API 层提供; - Mobile(apps/mobile/):依赖
core、editor、editor-mobile,用 React Native 承载同样的内核; - Web Clipper(extensions/web-clipper/):只依赖
clipper+theme,是依赖最少、体量最小的端。
🔑 关键洞察:四端 UI 框架各不相同(React / Electron / React Native),但数据、加密、同步、编辑器逻辑 100% 来自同一个 @notesnook/core 家族——这就是"四端统一"的架构本质:内核单一来源,外壳各写各的。
⚙️ monorepo 构建编排:一条命令驱动全仓
仓库根目录的 package.json 定义了统一任务调度器 tx(基于 scripts/execute.mjs),例如:
npm run start:web→ 启动 Web 端npm run test:core→ 只跑 core 包测试npm run build:android→ 构建安卓应用
首次安装时 scripts/bootstrap.mjs 会处理工作区引导,scripts/publish.mjs 负责发包。开发者只需克隆仓库(仓库地址:https://gitcode.com/gh_mirrors/no/notesnook)再执行 npm install,即可在任意子包内开发,而无需为每个平台单独搭环境。
🧭 新手阅读源码路线(建议收藏)
- 从 README.md 的 monorepo 结构表建立全局地图;
- 读 packages/crypto/ 理解端到端加密的最小闭环(体量小、无依赖噪音);
- 顺着 packages/core/src/index.ts 的导出列表逛
api/与database/,理解同步与本地存储; - 最后挑一个端(推荐 apps/web/)看它如何消费这些包完成组装。
13 个包看似繁多,实则是"加密内核 → 数据内核 → UI 外壳"三层解耦的经典产物。理解了这条依赖链,你就能看懂为什么 Notesnook 用同一份代码,就能在浏览器、桌面、手机和插件里给你同一种端到端加密的笔记体验。


