简介Couchbase Lite 面向 iOS/macOS 平台的轻量级嵌入式 NoSQL 数据库引擎完整源码为需要离线数据访问与多端同步的移动应用提供底层支撑。核心亮点包括文档导向的数据模型、本地高效查询以及基于跨平台 Couchbase Lite Core 的可靠同步能力特别适合即时通讯、物联网、移动办公等场景的开发者参考。资源共包含623个文件压缩包仅4.19MB主体涵盖183个h头文件、126个swift源码、121个m及41个mm实现文件同时附带xcconfig/xcscheme工程配置、sh构建脚本、sqlite3数据库及p12证书等便于直接查看底层实现与工程组织。目前已有37人学习下载适合iOS/macOS开发者深入理解嵌入式数据库的内核设计。通过这份源码读者可研究文档存储、数据同步、版本控制等核心模块的实际代码还可借鉴其跨平台工程结构和单元测试配置为自研或二次开发提供完整参考。1. 轻量级嵌入式 NoSQL为什么 iOS/macOS 端要单独存一份数据先看一个场景售后服务 App 里的维修工程师进了地下室信号只剩一格之前在线拉取的产品手册、历史工单全部打不开。服务端接口把数据做得再漂亮网络一断手机就是一块砖。Couchbase Lite 正是用来解决这个问题的它是一个轻量级嵌入式 NoSQL 数据库支持文档存储和数据同步适用于 iOS 和 macOS。相比 UserDefaults 只能存偏好Core Data 要为动态 JSON 反复迁移表结构Couchbase Lite 允许你直接把服务端 JSON 当成文档存进本地并在网络恢复后自动与后端完成双向同步。反直觉的结论是它并不是简单地把 SQLite 换了个名而是把“数据模型”和“同步链路”一起搬到了端上。拿到那个 .zip 压缩包意味着要面对的不仅是 SDK 集成还有一套离线优先的数据组织方式。适合的人在读这篇文章你的 App 需要本地先能读写再考虑同步你的字段结构一直在变你想少写一堆对象映射和增量更新代码。接下来我从选型判断开始一直讲到集成、同步和排错。2. Couchbase Lite 选型判断文档存储和查询能省多少事2.1 一个 JSON 文档字段到底省了什么迁移成本传统 SQLite 建表时要先定死字段id INTEGER, title TEXT, status TEXT。今天加一个priority字段就要ALTER TABLE老数据还要给默认值明天把tags从字符串改成数组又是一轮迁移。Core Data 更麻烦模型版本、映射模型、迁移选项缺一不可。到了实际项目里服务端下发的常常是半结构化 JSON字段层级深、部分字段可空、不同版本返回结构还不一样。把这种数据硬塞进关系表大量时间都花在“适配”而不是“使用”上。Couchbase Lite 的文档模型就是 JSON 树。一条维修工单可以写成这样外层是id、title、status内层再嵌customer对象、parts数组。新增字段不需要改表老文档没有这个字段也能照常查询。每次saveDocument会产生一个新版本系统字段_id和_rev由数据库管理业务字段可以随意增删。对 iOS/macOS 客户端来说最直观的改变是从服务端拿到的 JSON 几乎不需要做字段裁剪直接映射成MutableDocument存进去。需要注意一个边界文档虽然是 JSON 树但不代表可以无限嵌套。层级过深会让查询代码变得难读而且每次读写要解析整棵 JSON 树。我在实际项目里的习惯是嵌套超过三层就考虑拆成两个文档用documentId建立引用关系或者用数组索引查子对象。文档存储省掉的是建表迁移不是数据建模。2.2 查询与索引边界哪些需求它能接住Couchbase Lite 查询有两种常见写法一是QueryBuilder链式 API二是类 SQL 的字符串查询。如果只做等值过滤、排序、分页它和 SQLite 的体验非常接近它还支持JOIN、GROUP BY、COUNT/SUM/AVG这类聚合操作但不是所有关系型场景都适合在端上跑。判断方法是问三个问题查询条件是否都是文档字段的等值或范围比较这适合创建 value index。需不需要搜索正文里的关键词这需要建全文索引FTS。是否涉及两个集合的大规模 join如果 join 量很大说明数据建模可能不适合文档存储。查询性能的关键在索引。刚开始数据量只有几千条时全表扫描也能跑出 50ms等涨到十万条同一个查询可能变成 1 秒。Couchbase Lite 支持 value index、array index 和 FTS index后面我会给出建索引的代码。这里先记住原则WHERE、ORDER BY、JOIN里出现的字段都要考虑建索引但索引不是越多越好每多一个索引写入时的成本就高一份。聚合操作建议克制。端上数据量如果只有几万条求和、分组还能接受一旦要按十几个维度分析数据直接把原始文档同步到端上就不划算了更合理的方式是服务端聚合好再同步聚合结果文档。2.3 和 Core Data / SQLite / Realm 比什么时候选 Couchbase Lite维度Core DataSQLiteRealmCouchbase Lite数据形态对象图关系表对象/文档JSON 文档Schema 变更迁移成本高手写 ALTER需要迁移无需迁移查询方式NSPredicateSQL谓词QueryBuilder / SQL内置同步无无有但依赖服务组件自带 Sync Gateway 通道二进制大文件不适合不适合支持附件支持 Blob 附件Core Data 的强项是对象图和 undo/redo适合文档型应用、绘图类工具SQLite 的强项是关系查询和成熟生态适合数据模型稳定、查询复杂的单机场景Realm 的 API 上手快但数据同步要自己搭服务端。Couchbase Lite 最独特的价值在于它把“本地数据库”和“增量同步”做成了一件事而且文档结构和服务端 JSON 天然对齐。什么时候不要选它如果项目完全没有同步需求数据量也不大SQLite 更轻如果 App 的主要数据是高度关联的关系模型比如订单、明细、库存之间要频繁 join关系表依然更合适。Couchbase Lite 擅长的是“半结构化文档 端上可用 多端收敛”这个定位和移动端业务场景正好重合。3. iOS 项目集成 Couchbase Lite从零写入第一条文档3.1 用 Swift Package Manager 引入 Couchbase Lite两步搞定当前常见做法是用 Swift Package ManagerXcode 打开菜单 File → Add Package Dependencies输入官方仓库地址github.com/couchbase/couchbase-lite-ios版本规则选 Up to Next Major添加后 target 会自动链接CouchbaseLiteSwift代码里直接import CouchbaseLiteSwift就能编译。如果你的团队还在用 CocoaPodsPodfile 写法如下platform :ios, 13.0 use_frameworks! target YourApp do pod CouchbaseLiteSwift end执行pod install之后打开.xcworkspace。两种方式二选一不要混用否则容易出现重复符号。SPM 更适合新项目CocoaPods 更适合团队已有私有源和统一规范。集成完之后先做一件事跑一个空工程并成功打开数据库确认不是编译通过但运行时找不到 framework。3.2 打开数据库与写入第一条 JSON 文档数据库实例最好不要每次操作都新建一个Database对应一个数据库文件建议在 App 启动时打开一次后续通过单例或依赖注入传给业务层。下面是打开数据库并写入第一条文档的完整示例import CouchbaseLiteSwift // 指定目录放在 Application Support 下避免沙盒路径写死 let dir FileManager.default .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0] .appendingPathComponent(cbl, isDirectory: true) .path let config DatabaseConfiguration() config.directory dir let db try Database(name: taskbox, config: config) // 构造文档id 不传会自动生成 UUID let doc MutableDocument(id: task-1001) doc.setString(检修变频器, forKey: title) doc.setString(todo, forKey: status) doc.setInt(3, forKey: priority) doc.setValue([强电, 售后], forKey: tags) doc.setDate(Date(), forKey: createdAt) try db.saveDocument(doc) print(文档已写入: \(doc.id))这里有几个参数值得解释DatabaseConfiguration.directory如果不设置默认也会落在系统应用支持目录但显式指定路径的好处是方便测试时切换数据库也方便排查沙盒权限问题。MutableDocument(id:)的id是业务主键如果传相同 id 再保存数据库会把它当成更新而不是新增这一点和关系表的主键冲突很像。setValue接收数组和字典内部会自动做类型转换不要把一个自定义 NSObject 直接塞进去存取时会出意外。保存之后如果需要确认数据真正落盘最简单的方式是立刻按 id 读一次。3.3 读取、更新、删除与数组和字典操作差不多读取和更新用下面的代码// 按 id 读取 if let task db.document(withID: task-1001) { let title task.string(forKey: title) ?? let tags task.array(forKey: tags)?.toArray() ?? [] print(标题: \(title), 标签: \(tags)) } // 更新基于旧文档创建可变副本 if let old db.document(withID: task-1001) { let updated old.toMutable() updated.setString(done, forKey: status) updated.setInt(4, forKey: priority) try db.saveDocument(updated) } // 删除 if let task db.document(withID: task-1001) { try db.deleteDocument(task) }逻辑说明document(withID:)返回的是不可变快照直接改上面的值没有意义必须调用toMutable()生成新版本。保存时数据库会比较本地 revision 是否还是最新如果期间有其他线程或同步链路改了同一个文档这里会抛冲突错误后面避坑章节会专门讲。deleteDocument在 Couchbase Lite 里不是物理删除而是写入一个墓碑标记这个标记会参与同步告诉服务端和其他设备这条文档已删除。如果不想让墓碑无限堆积可以定期调用db.compact()。如果查询不再只是个需要直接遍历全部文档也可以let query QueryBuilder .select(SelectResult.all()) .from(DataSource.database(db)) let rows try query.execute() for row in rows { if let dict row.dictionary(forKey: db) { print(dict.string(forKey: title) ?? ) } }SelectResult.all()会把整条文档放在结果集的db字典里这是 Couchbase Lite 的固定行为新手第一次查的时候容易取错 key。业务里更推荐只 select 需要的字段比如SelectResult.expression(Expression.property(title))这样能减少内存占用和序列化开销。4. 从本地文档到数据同步配置 Sync Gateway 与复制通道4.1 Sync Gateway 到底在同步链路里扮演什么角色Couchbase Lite 本身是端上数据库它不直接连接传统的数据库服务端口。常见部署模型是iOS/macOS 端通过 WebSocket 连接 Sync GatewaySync Gateway 再连接 Couchbase Server。Sync Gateway 负责用户认证、文档访问控制、通道路由、增量同步和冲突收敛。没有这个环节端上的数据无法进入统一后端。对于只有几个客户端的小团队可能会觉得多部署一个服务很重。但实际上 Sync Gateway 的配置比想象中简单而且它把设备注册、权限控制、同步历史这些原本要自己写的事都接住了。如果项目是纯离线单机不需要同步那可以完全不管 Sync GatewayCouchbase Lite 依然能作为普通嵌入式数据库工作。4.2 自建 Sync Gateway 的最小配置先把 Couchbase Server 里创建一个 bucket名字和下面配置里的bucket保持一致。然后写一个最小配置文件sg-config.json{ admin_interface: 127.0.0.1:4985, databases: { taskbox: { bucket: taskbox, users: { GUEST: { disabled: true } }, sync: function(doc, oldDoc) { channel(doc.channels); } } } }启动命令是./sync_gateway ./sg-config.json。admin_interface是管理端口客户端不访问它客户端连的是默认4984端口。sync函数是一个 JavaScript 函数channel(doc.channels)表示把文档里的channels字段当作通道名客户端必须拿到对应通道权限才能同步。GUEST.disabled true表示不允许匿名访问生产环境必须关掉。这里最容易踩的坑是只建了 Sync Gateway没建 Couchbase Server bucket。Sync Gateway 启动时会尝试连 bucket如果 bucket 不存在数据库会一直停在offline状态客户端连上来没有任何响应。先确认curl 127.0.0.1:4985/taskbox/能返回 bucket 信息再继续排查端侧。4.3 iOS/macOS 端 Replicator 的 Swift 配置端侧同步的核心类是Replicator。下面这段代码创建了一个持续双向同步的复制器import CouchbaseLiteSwift // 连接 Sync Gateway 的数据库端点 let url URL(string: ws://127.0.0.1:4984/taskbox)! let target URLEndpoint(url: url) var config ReplicatorConfiguration(database: db, target: target) config.replicatorType .pushAndPull config.continuous true config.authenticator BasicAuthenticator(username: alice, password: pass) let replicator Replicator(config: config) replicator.addChangeListener { change in if let error change.status.error { print(同步失败: \(error.localizedDescription)) } else { let progress change.status.progress print(已完成 \(progress.completed)/\(progress.total)) } } replicator.start()replicatorType有三个取值.push只上传本地改动.pull只从服务端拉取.pushAndPull双向同步。绝大多数业务应该用.pushAndPull。continuous决定是一次性同步还是持续同步如果设成false数据同步完成一次就停了之后本地再有新改动不会自动上传。聊天类、工单类应用建议设true。BasicAuthenticator的用户名密码要和 Sync Gateway 里创建的用户一致认证失败时连接会直接关闭。还有一个隐蔽点如果 Sync Gateway 没配置 TLS 证书客户端地址要用ws://而不是wss://。从 iOS 9/macOS 10.11 开始系统默认禁止明文网络请求需要在 Info.plist 里加例外keyNSAppTransportSecurity/key dict keyNSAllowsLocalNetworking/key true/ /dictNSAllowsLocalNetworking允许本地网络明文请求适合开发阶段连接本机 Sync Gateway。真机连局域网调试时如果依然报 ATS 错误再考虑对具体服务器域名加NSExceptionDomains不要图省事全局开启NSAllowsArbitraryLoads。4.4 冲突策略自定义 Resolver 与合并原则当两个设备同时修改同一条文档同步回来后就会产生冲突。Couchbase Lite 的默认行为是保留一个版本但这不一定符合业务预期。比如 iOS 端改了任务标题macOS 端改了任务状态理想结果是合并两个改动而不是用标题覆盖状态。自定义冲突解决器通过实现ConflictResolver协议完成final class LastWriteWinsResolver: ConflictResolver { func resolve(conflict: Conflict) - Document? { // 只有一端有文档时保留存在的那份 guard let local conflict.localDocument, let remote conflict.remoteDocument else { return conflict.localDocument ?? conflict.remoteDocument } // 按业务时间戳选择较新版本 let localTime local.double(forKey: updatedAt) let remoteTime remote.double(forKey: updatedAt) return localTime remoteTime ? local : remote } } config.conflictResolver LastWriteWinsResolver()这里的localDocument是本地当前版本remoteDocument是同步回来的远端版本。如果不做字段级合并至少保证“最新时间戳赢”如果要做字段级合并可以在 resolver 里遍历两个文档的字段按字段分别取新值。注意resolver 里不要做耗时操作也不要访问数据库它只负责返回一个解决后的文档对象。5. Couchbase Lite 避坑与常见问题排查5 个真翻车点5.1 数据库文件暴涨同步后磁盘占满现象App 跑了半年Couchbase Lite 数据库文件从 20MB 涨到 800MB用户反馈存储空间告急。原因Couchbase Lite 每次更新文档都会保留旧 revision同步过程中还会积累删除墓碑另一个常见原因是把图片转成 base64 直接塞进文档字段一个 2MB 的图片变成约 2.7MB 字符串再更新几次磁盘占用立刻翻倍。解决二进制数据不要塞 JSON 字段用 Blob 附件。示例let blob try Blob(contentType: image/jpeg, data: imageData) let doc MutableDocument(id: profile-001) doc.setBlob(blob, forKey: avatar) try db.saveDocument(doc)Blob 由数据库管理同步时可以按需拉取不会因为文档更新反复复制整段二进制。另外定期调用db.compact()清理无用的旧版本和墓碑。不要每次用户操作后都 compact那会拖慢写入一般放在 App 进入后台或启动后的空闲时段做一次。5.2 同步没反应Xcode 控制台报 ATS 错误现象Sync Gateway 已经启动replicator.start()也调了状态一直停在idle控制台出现 “App Transport Security policy requires a secure connection”。原因iOS/macOS 对http://和ws://明文连接默认拦截。开发环境用本地 Sync Gateway地址是ws://127.0.0.1:4984正好被 ATS 拦下。解决在 Info.plist 添加NSAppTransportSecurity→NSAllowsLocalNetworking为true。如果从本地同时起多个服务优先用localhost而不是局域网 IP本地网络权限弹窗更少。注意改完 Info.plist 必须杀掉 App 重新运行只重新编译有时不生效。5.3 查询越来越慢一查就是全表扫描现象数据量从 1 万涨到 10 万后原本 50ms 的查询变成 1 秒翻页开始卡顿。原因没建索引查询引擎只能线性扫描所有文档。WHERE条件字段、ORDER BY字段都没有索引时数据量越大差距越明显。解决给常用过滤字段建 value index。let index IndexBuilder.valueIndex( ValueIndexItem.expression(Expression.property(status)) ) try db.createIndex(index, withName: idx_status)索引字段顺序有讲究等值条件放前面范围条件放后面。比如先过滤status再按priority排序可以考虑建组合索引。数组字段用ValueIndexItem.expression(Expression.property(tags))做 array index可以查询数组包含某个值。全文搜索用IndexBuilder.fullTextIndex但要注意 FTS 索引和 value index 不能互相替代。5.4 两端同时改同一条文档saveDocument 抛 conflict现象用户在 iOS 离线改任务名称另一台 macOS 在线改同一任务状态两边同步后其中一端收到conflict错误甚至改动被覆盖。原因Couchbase Lite 采用乐观并发控制。保存文档时数据库会检查当前本地 revision 是否还是上次读取的那一版如果期间文档被同步链路更新过当前 revision 变了保存就会失败。解决先设置自定义ConflictResolver让它处理同步回来的冲突。保存前的短期冲突则用“读最新版再改”的策略。下面是一个带重试的合并保存函数func saveWithRetry(document: Document, merge: (MutableDocument) - Void, retry: Int 3) throws { var current document for _ in 0..retry { let mutable current.toMutable() merge(mutable) do { try db.saveDocument(mutable) return } catch { // 只有冲突才值得重试 guard case CouchbaseLiteError.conflict error else { throw error } if let latest db.document(withID: document.id) { current latest } } } }这个函数不是银弹业务合并逻辑还要自己写比如把title取 local把status取 remote。关键教训是不要在 UI 线程用try?吞掉冲突后直接覆盖那样一定会丢数据。5.5 macOS 沙盒下数据库路径不对现象App 在 Xcode 里开发调试一切正常打包后首次启动可以打开重启后报 “Unable to open database”或者数据库文件根本没生成。原因macOS App Sandbox 会把应用的真实数据目录重定向到容器内路径形如~/Library/Containers/bundle-id/Data/Library/Application Support。如果代码硬编码了~/Library/Application Support或把旧路径存进 UserDefaults沙盒下就访问不到真正的位置。解决不要拼写固定路径用系统 API 动态获取。同时确认沙盒权限let base FileManager.default .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0] let dbDir base.appendingPathComponent(cbl, isDirectory: true) try FileManager.default.createDirectory(at: dbDir, withIntermediateDirectories: true)如果 App 有多个进程或 Extension需要共享数据库可以改用 App Group 容器路径。Entitlements 里还要打开com.apple.security.network.client否则 Replicator 无法发起网络连接这也是沙盒下同步一直失败的常见原因。6. 进阶用 Live Query 索引搭建本地搜索与增量更新6.1 全文索引与一条可复用的查询进入进阶之前先解决一个高频需求在文档里搜关键词。普通 value index 只能做等值和范围匹配不支持LIKE %关键词%的高效搜索。给title字段建 FTS 索引let ftsIndex IndexBuilder.fullTextIndex( FullTextIndexItem.expression(Expression.property(title)) ).ignoreAccents(true) try db.createIndex(ftsIndex, withName: idx_title_fts)查询时用FullTextExpression.index(idx_title_fts).match(变频器)。注意 FTS 只对分词后的词匹配中文分词效果取决于 SDK 内建策略。如果搜索需求复杂建议提前拿真实语料测试命中率不要上线后才发现搜不到。6.2 用 Live Query 监听变化驱动 UI数据库变化时需要刷新列表最朴素的方式是每次saveDocument后重新查。但一个页面可能依赖多个查询条件改动来源又包括同步线程这时候用LiveQuery更稳。它会在底层数据变化后重新执行查询并通知监听者let query QueryBuilder .select(SelectResult.expression(Expression.property(title))) .from(DataSource.database(db)) .where(Expression.property(status).equalTo(Expression.string(todo))) let liveQuery query.toLiveQuery() let token liveQuery.addChangeListener { change in // 回到主线程刷新 UI DispatchQueue.main.async { let rows try? change.results?.allResults() // 更新 UITableView / SwiftUI 数据源 } } liveQuery.start()调用liveQuery.start()之后任何导致查询结果变化的文档写入都会触发回调。注意回调线程不是主线程UI 刷新要主动切回主线程。addChangeListener返回的 token 要持有手动停止时调用token.remove()避免控制器释放后回调还在跑。6.3 验证同步一致性的三步自查如果发现两端数据不一致按顺序查三个地方先查 Sync Gateway 侧数据库里有没有产生冲突日志再查端侧ConflictResolver是否被调用如果从没调用过说明两个端并没有真正同时修改同一文档最后查 Replicator 的replicatorType和continuous配置pushAndPull且continuous true是最稳妥的组合。我自己的习惯是在开发环境固定一个错误复现路径两台模拟器连同一个 Sync Gateway一台离线改数据另一台在线改同一字段再恢复网络观察冲突 resolver 返回的结果是否符合预期。这个动作做完才算真正理解了同步链路而不是只“能连上”。排查里吃过最多的亏还是第 5.2 条那个 ATS 问题每次换电脑都要重新确认 Info.plist 没丢。另一个固定动作是给每个查询单独建索引写完查询先看一眼explain而不是等到线上用户反馈卡顿。这套本地数据库加同步链路的组合值得投入但一定要把离线优先和冲突合并当成一等公民设计。希望帮到你。本文还有配套的精品资源点击获取