Syncular：离线优先的 SQL 同步方案，客户端本地 SQLite + 服务端单一提交日志

原文来源：GitHub — syncular/syncular — 服务端权威的离线优先 SQL 同步框架：客户端持有真实本地 SQLite，写入走乐观 outbox，服务端单一提交日志作为事实来源，TypeScript 与 Rust 双核心实现。

做本地优先（local-first）应用的人最头疼的问题之一，就是数据同步。把 SQLite 放在客户端意味着离线可用、秒开、数据属于用户，但一旦涉及多端同步，冲突处理、提交顺序、服务端权威性这些问题的复杂度会立刻失控。Syncular 就是冲着这个问题来的：一个服务端权威（server-authoritative）、离线优先（offline-first）的 SQL 同步框架，在 Hacker News 上以 Show HN 形式发布后拿到了 60+ 分。

它解决什么问题

先看典型的同步方案痛点。传统的客户端-服务端架构里，客户端永远是"瘦"的——数据存在服务器，离线就没得用。反过来，纯本地应用（比如单机 SQLite）数据体验好，但没法多端同步。中间地带是各种 sync 中间件，但很多方案要么要求客户端用特定的数据模型（如 KV、文档），要么把冲突处理留给开发者自己写，要么同步引擎本身是个黑盒。

Syncular 的定位很明确：客户端保持一个真实的本地 SQLite 数据库——浏览器里用 OPFS（Origin Private File System）承载，其他平台用原生 SQLite。你的应用代码照常执行 SQL 查询，读写都是本地完成，感觉就像在写一个单机应用。写入通过一个乐观的 outbox（出站队列）记录，服务端维护一条有序的提交日志作为唯一事实来源（source of truth）。同步过程对你透明，冲突由服务端权威地裁决。

架构：双核心 + spec-first

Syncular 最值得看的不是功能列表，而是它的工程组织方式。

TypeScript 和 Rust 双核心。 Web 端核心基于 @sqlite.org/sqlite-wasm，Rust 端核心提供原生性能，并带一个 C-ABI FFI crate，因此能绑定到 Tauri、React Native、Swift、Kotlin、Flutter——几乎覆盖了所有主流客户端平台。两个核心由一套实现无关的一致性测试套件（conformance suite）约束在锁步状态：同一批场景，两个核心都必须通过。

Spec-first 开发。 仓库里的 SPEC.md 是规范性的，spec/vectors/ 是黄金测试向量；当规范与代码冲突时，改的是代码。这保证了协议本身是经过推敲的契约，而不是某个实现的附属品。

测试纪律。 集成场景用 loopback 内存传输跑，故障注入在传输接口做，测试等待显式的就绪信号（禁止 sleep），真实 socket 测试极少且被隔离。这意味着同步引擎最难的故障路径——断网、重连、乱序、并发写——都有系统的测试覆盖。

包结构上，packages/server 提供 handleSyncRequest(bytes, ctx) 加存储/认证接口，存储层支持 SQLite、Postgres 和 Cloudflare D1；框架绑定有 Hono 和 Workers 两套。客户端侧有 React hooks 包、schema 类型生成器（typegen）、按列加密的 E2EE 原语（crypto）和 Yjs CRDT 合并器（crdt-yjs）。值得一提的还有 @syncular/testkit——内存回环模拟真实服务器加客户端的测试工具包，你可以在不部署任何服务的情况下测同步逻辑。

快速上手

项目用 Bun 作为包管理器和运行时（这也是它出现在 Bun 生态圈的原因之一）。创建一个新应用只需要一条命令：

bun create syncular-app my-app

核心用法分两层。服务端实现一个 handleSyncRequest 处理器（存储选 SQLite/Postgres/D1 之一），挂到 Hono 或 Workers 上；客户端用 @syncular/client 连接，@syncular/react 提供 hooks 管理同步状态。浏览器端数据持久化在 OPFS，同步走 WebSocket。

演示站点甚至把整个同步服务器跑在了浏览器里的 Web Worker 中——用 sqlite-wasm 模拟 D1 存储，realtime 通道代替 WebSocket，两个浏览器窗格之间实时同步 todo 数据，全程静态文件、无后端。想先体验同步是什么感觉，直接打开 demo 就能玩。

成熟度与限制

Syncular 还在早期：GitHub 上约 90 stars、1231 次提交，0.2.0 版本刚为 npm（13 个包）和 crates.io 做好发布准备，Apache-2.0 许可。活跃度不错——主分支近几周几乎天天有提交，包括依赖审计、安全公告修复（svgo/postcss/sharp）和 CI 供应链加固（workflow action 全部按 commit SHA 固定）。

另外它有一个很有性格的 AGENTS.md：明确欢迎 LLM 参与写测试、复现、基准、文档和生产代码，但要求人类严格 review 每一行，低质量的机器生成 PR 会被直接关闭。对"AI 时代开源项目怎么管"感兴趣的人，这份政策本身都值得一读。

适合谁用

适合：做本地优先应用的独立开发者和小团队，尤其是需要离线能力 + 多端同步的产品——笔记类、任务管理、带离线模式的业务工具；用 Tauri 或 React Native/Flutter 打包、想共享一套同步协议的项目；以及受够了黑盒同步引擎、想要"服务端权威 + 可审计提交日志"的人。Bun 用户上手最顺。

不适合：纯在线应用（杀鸡用牛刀）；需要复杂权限模型或按行级 ACL 的多人协作产品（Syncular 的权威裁决是提交日志级的，细粒度权限需要自己扩展）；对生态成熟度要求极高、希望有丰富第三方教程和插件的团队——它还很新，文档和社区都在建设期。

同类方案对比

• PowerSync / Supabase Realtime：同类 SQL 同步服务，但偏向托管服务，Syncular 更强调自托管和"你操作得了的同步"。
• Yjs / Automerge：CRDT 文档同步，适合文本/协作编辑；Syncular 走的是 SQL + 提交日志路线，服务端权威，两者理念不同（仓库里也有 Yjs CRDT 合并器作为可选增强）。
• 自研同步：如果只是"离线写、联网传"，自己写 outbox + 冲突解决可能半年后就会遇到你没想过的边界情况；Syncular 把这些坑提前替你踩了。

一句话：如果你认同"本地数据是体验，服务端日志是事实"，Syncular 值得放进候选清单。