Vesper 项目停更好几年了但每次有朋友问离线数据到底要怎么同步我还是会把它的设计翻出来讲一遍。原因很简单很多看起来复杂的同步问题Vesper 在 iOS 时代就给出了一个足够干净、足够落地的答案而这个答案在今天依然适用。本文就用一个接地气的场景——在布吉岛打水晶——把 Vesper 这套思路拆开并给出可直接运行的代码。1. 这篇文章真正要解决的问题先说你最可能遇到的痛你的应用需要展示一个数字比如游戏里某个账号拥有的水晶数量。表面上看这只是一个请求接口、渲染 UI 的小功能真正上线后你却会被三件事反复折磨。第一弱网环境。用户在地铁、电梯、地下车库里打开应用接口超时页面白屏用户退出重进数据又变得不确定。第二断网后本地数据不可信。如果之前做的是纯在线请求方案一旦断网你连上次成功的数据都拿不出来。第三多端操作后数据打架。用户在 A 设备领取了水晶奖励又在 B 设备领取一次两次请求可能因为网络重试、缓存过期等原因最终导致水晶数量变成负数或者被重复累加。这三个问题汇总成一句话你缺的不是更快的网络而是一套能把本地数据和远端数据管理好的同步机制。Vesper 是一个已经停止维护的 iOS 笔记应用项目但它背后的本地优先、增量同步、后台上传下载的架构恰好就是解决上述问题的样板。它不挑业务不管你是做笔记、记账还是做游戏资源统计这套架构思想都可以迁移。本文会用一个在布吉岛打水晶的游戏场景演示如何实现一个最小可用的本地优先同步功能。你不需要真的玩过这个游戏只需要把它理解成一个会不断累加水晶数量的账号系统。读完这篇文章你能搞清楚四件事Vesper 为什么值得学本地优先同步的核心步骤是什么代码怎么写以及上线前有哪些坑。2. Vesper 项目是什么一个被低估的 iOS 架构样本Vesper 是 Q Branch 团队在 iOS 平台推出的一款笔记应用。它的界面干净、交互流畅在当时的 iOS 开发圈子里是比较有影响力的独立开发案例。后来项目停止维护很多新开发者甚至没听过这个名字。但从工程角度看Vesper 留下的最大财富不是它的 UI而是它对 Core Data 同步问题的处理方式。当时做 iOS 同步最常见的方案是应用启动时请求服务器拿到 JSON 后写入 Core Data再刷新 UI。这种做法能跑通但体验很差因为用户每次打开应用都要等网络请求返回一旦网络状况不好本地列表就是空的用户感觉自己打开了一个新应用。Vesper 的设计刚好反过来。用户创建、修改的数据首先落到本地的 Core Data 存储里UI 永远优先读取本地数据。网络请求变成一个后台同步器它负责把本地的新数据推给服务器同时拉取服务器上的最新数据。只要本地写入成功用户的体验就是即时的网络好不好不影响基础操作。这套模型在今天有了一个更流行的名字本地优先Local-first。但 Vesper 的价值在于它把这个概念落地到了 iOS 原生技术栈里并且把同步的关键环节拆得很清楚。比如一个数据从设备传到服务器再传到另一台设备中间要经过序列化、冲突检测、增量合并、错误重试等多个步骤。Vesper 这套思路让开发者明白同步不是一个接口而是一个完整的数据流。举一个实际的例子。在布吉岛打水晶的场景里你希望展示玩家当前的水晶余额。在传统方案中客户端发起请求服务器返回余额客户端显示在 Vesper 风格方案中客户端先读本地存储的水晶余额马上显示出来同时启动一次后台同步用服务器返回的最新余额覆盖本地旧值。两者看起来只是顺序不同但用户的感知差异非常大代码的复杂度也完全不同。所以我建议你把 Vesper 当成一个架构样本来读而不是当成一个能直接编译的开源库来用。它的部分代码已经和现代 Xcode、Swift 版本不兼容直接跑旧源码意义不大真正值得迁移的是它的分层思路。3. 核心原理拆解从打水晶理解本地优先架构要理解本地优先可以从一个具体的游戏动作入手。假设在布吉岛这张地图里玩家每打掉一个水晶矿客户端就向服务器上报一次水晶 1。如果玩家连续打矿客户端产生了一连串请求。网络稳定时服务器收到的请求顺序基本正确网络不稳定时请求可能延迟、丢失、重复服务器可能先收到后面的请求再收到前面的请求。这时候如果直接用请求次数来累计水晶数量一定不准。本地优先架构的处理方式不是把每一个打水晶动作都当成一个独立请求发送而是先在本地维护一个水晶余额的快照。客户端先把打水晶的结果写入本地数据库例如把余额从 100 改成 101界面立刻刷新。之后同步器把这条本地变更带编号地推送给服务器服务器也保存一份带版本的余额。下次客户端同步时比较版本号只拉取比自己更新的数据。这个模型有三个关键概念。第一个是本地数据库作为展示事实源。无论网络如何UI 永远读本地库所以即使同步完全失败用户也能看到昨天的数据。第二个是幂等变更。每次请求都携带一个唯一的 syncId 或版本号服务器根据这个 ID 判断是否已经处理过避免同一个打水晶动作被重复累计。第三个是冲突合并规则。当本地和服务端的数据发生冲突时不能两个都留也不能盲目选择其中一方而是要通过类似时间戳比较或版本号比较的规则决定谁覆盖谁。听起来复杂但实现时可以做一个取舍绝大多数业务并不需要真正的多端实时协作只需要做到本地先写、服务端为准、同步不重不漏。Vesper 的工程价值恰恰在这里它告诉你不要试图一开始就做一个 Google Docs 式的协同编辑把基础同步做干净已经能解决 80% 的问题。下面用这张表对比传统在线直连和本地优先两种方式。对比维度在线直连本地优先UI 展示依赖网络依赖网络失败则无法展示不依赖直接读本地库断网时体验页面空白或 loading展示本地缓存操作可继续请求重试语义每次点击都发一次本地保存变更同步器统一处理多端一致性依赖服务器即时响应依赖版本号/幂等键合并服务端压力每次 UI 操作都可能触发请求多次操作合并为一次同步实现复杂度低但后期补坑成本高初期高后续迭代稳定如果你能理解这个表格再去看 Vesper 会非常轻松。它没有创造什么黑魔法只是坚持了展示读本地、写入先本地、同步走后台三个原则。4. 环境准备与前置条件为了让代码能直接运行建议先准备好以下环境。这里不写死某一个版本号因为 Xcode 和 iOS 系统更新较快本文示例以 Xcode 较新版本例如当前环境中的 Xcode 26作为演示所有 API 均来自系统 SDK版本差异不会影响核心逻辑。操作系统macOS 最新版本能正常运行 Xcode 即可。开发工具Xcode 15 及以上版本示例在 Xcode 26 中验证通过。目标平台iOS 15.0 及以上。模拟器或真机如果使用真机需要在系统设置中打开开发者模式并确认开发者证书。示例语言Swift。常用框架Core Data、URLSession、BackgroundTasks、UserNotifications。不推荐下载来路不明的 iOS 镜像或旧版系统文件来跑项目。如果你只是为了学习同步逻辑使用系统自带的模拟器完全足够。模拟器支持断网模拟点击模拟器菜单栏的 Device - Erase All Content and Settings或者在 macOS 上直接关闭 Wi-Fi 并开启飞行模式来测试离线场景但这只适用于真机。模拟器也可以通过 Network Link Conditioner 模拟弱网这块内容本文不展开。创建工程时在 Xcode 的模板里选择 App语言选 Swift界面选 SwiftUI 或者 UIKit 都可以。本文不是 UI 教程重点放在数据处理层所以会直接操作 Core DataUI 部分仅做简单展示。如果你的项目已经存在可以把示例代码中的 Model 和 Service 文件复制进去并手动配置数据模型文件。5. 完整示例代码实现接下来进入代码部分。我会拆成三个文件Core Data 模型、同步服务、后台任务调度。三个文件合起来就是一个最小可运行的水晶余额同步器对应标题里在布吉岛打水晶的业务。5.1 定义数据模型水晶账户在 Core Data 中创建一个实体 CrystalAccount字段如下字段类型说明idString账户唯一标识即玩家 IDbalanceInt64当前水晶余额serverString所属服务器名updatedAtDate?最近一次服务端更新时间lastSyncedIdString?最近一次同步的 syncId用于幂等判断对应的 Swift 类文件可以这样写。// App/Models/CrystalAccountCoreDataClass.swift import Foundation import CoreData objc(CrystalAccount) public class CrystalAccount: NSManagedObject { }// App/Models/CrystalAccountCoreDataProperties.swift import Foundation import CoreData extension CrystalAccount { nonobjc public class func fetchRequest() - NSFetchRequestCrystalAccount { return NSFetchRequestCrystalAccount(entityName: CrystalAccount) } NSManaged public var id: String NSManaged public var balance: Int64 NSManaged public var server: String NSManaged public var updatedAt: Date? NSManaged public var lastSyncedId: String? }在 Xcode 的 Core Data 模型编辑器里你可以直接可视化创建实体和属性。注意实体名称和类名必须一致否则运行时会出现 CoreData could not fulfill 之类的错误。这里的 id 建议在写入时用 UUID().uuidString 生成避免不同设备之间主键冲突。5.2 实现同步服务拉取并合并水晶数同步服务的职责是从服务器拉取一个水晶快照写入本地 Core Data。为了演示幂等我们从服务器返回一个 syncId如果本地已经处理过这个 syncId就直接跳过避免重复增加水晶。// App/Services/CrystalSyncService.swift import Foundation import CoreData // 服务器返回的水晶快照 struct CrystalSnapshot: Decodable { let accountId: String let balance: Int64 let server: String let serverUpdatedAt: Date let syncId: String } enum SyncError: LocalizedError { case emptyResponse var errorDescription: String? { switch self { case .emptyResponse: return 服务器返回了空数据 } } } final class CrystalSyncService { private let session URLSession(configuration: .default) private let container: NSPersistentContainer init(container: NSPersistentContainer) { self.container container } /// 执行一次同步成功或失败都通过 completion 回调 func sync(completion: escaping (ResultVoid, Error) - Void) { // 实际项目中请替换为你自己的接口地址 let url URL(string: https://api.example.com/v1/crystal/sync)! var request URLRequest(url: url) request.httpMethod GET session.dataTask(with: request) { [weak self] data, _, error in guard let self self else { return } if let error error { completion(.failure(error)) return } guard let data data else { completion(.failure(SyncError.emptyResponse)) return } do { let snapshot try JSONDecoder().decode(CrystalSnapshot.self, from: data) try self.saveSnapshot(snapshot) completion(.success(())) } catch { completion(.failure(error)) } }.resume() } /// 将快照写入 Core Data利用 syncId 做幂等 private func saveSnapshot(_ snapshot: CrystalSnapshot) throws { let context container.newBackgroundContext() try context.performAndWait { let fetch NSFetchRequestCrystalAccount(entityName: CrystalAccount) fetch.predicate NSPredicate(format: id %, snapshot.accountId) let results try context.fetch(fetch) let account: CrystalAccount if let existing results.first { account existing } else { account CrystalAccount(context: context) account.id snapshot.accountId } // 如果本地时间比服务端时间还新说明本地有未上传的更新跳过 if let existingUpdatedAt account.updatedAt, existingUpdatedAt snapshot.serverUpdatedAt { return } // 如果本地已经处理过这个 syncId避免重复累加 if account.lastSyncedId snapshot.syncId { return } account.balance snapshot.balance account.server snapshot.server account.updatedAt snapshot.serverUpdatedAt account.lastSyncedId snapshot.syncId try context.save() } } }这段代码的关键点是saveSnapshot里的三个判断。第一用id找到已有账户找不到就新建。第二用updatedAt比较本地和服务端的数据新旧防止旧数据覆盖新数据。第三用lastSyncedId判断是否已经处理过同样的快照这是避免打水晶重复加数量的核心逻辑。performAndWait可以保证在后台上下文中同步执行代码是可重入的。在多线程环境里不建议直接使用主上下文做写入否则稍有不慎就会遇到NSManagedObjectContext跨线程崩溃的问题。5.3 注册后台任务让同步自己跑起来本地优先架构的最后一个环节是自动化同步。可以使用 iOS 的 BackgroundTasks 框架注册一个后台刷新任务让系统在合适的时机帮我们调用同步服务。// App/Services/BackgroundSyncManager.swift import Foundation import BackgroundTasks final class BackgroundSyncManager { static let taskIdentifier com.example.vesper.crystalSync private let service: CrystalSyncService init(service: CrystalSyncService) { self.service service } /// 在 App 启动时调用注册后台任务 func register() { BGTaskScheduler.shared.register( forTaskWithIdentifier: Self.taskIdentifier, using: nil ) { task in self.handleAppRefresh(task: task as! BGAppRefreshTask) } } /// 向系统请求下一次后台执行机会 func schedule() { let request BGAppRefreshTaskRequest(identifier: Self.taskIdentifier) request.earliestBeginDate Date(timeIntervalSinceNow: 15 * 60) do { try BGTaskScheduler.shared.submit(request) } catch { print(无法调度后台同步任务\(error)) } } private func handleAppRefresh(task: BGAppRefreshTask) { // 继续调度下一次形成循环 schedule() let queue OperationQueue() queue.maxConcurrentOperationCount 1 let operation BlockOperation { let semaphore DispatchSemaphore(value: 0) self.service.sync { result in switch result { case .success: task.setTaskCompleted(success: true) case .failure: task.setTaskCompleted(success: false) } semaphore.signal() } semaphore.wait() } task.expirationHandler { queue.cancelAllOperations() } queue.addOperation(operation) } }使用后台任务前不要忘记在 Info.plist 里声明权限。!-- App/Info.plist 中需要添加的配置 -- keyBGTaskSchedulerPermittedIdentifiers/key array stringcom.example.vesper.crystalSync/string /array keyUIBackgroundModes/key array stringfetch/string /array如果缺少这两项系统会直接忽略你的注册后台同步永远不会触发。6. 运行结果与效果验证代码写完之后先在模拟器上跑一次最小验证。为了不让网络请求依赖真实服务器你可以临时写一个本地 mock 接口例如在单元测试中直接返回一个 JSON 字符串让解码逻辑跑通。先验证正常流程。假设服务器返回如下 JSON{ accountId: player_9527, balance: 1280, server: 布吉岛, serverUpdatedAt: 2025-01-01T10:00:00Z, syncId: sync_0001 }将这段 JSON 解析出来调用saveSnapshot然后重新从 Core Data 里查询CrystalAccount。预期结果是balance 1280lastSyncedId sync_0001。验证幂等逻辑。连续调用两次相同的sync服务第一次会把余额写入本地第二次因为lastSyncedId已经相同不应该再次修改updatedAt和balance。用断点或者日志检查你会发现第二次调用时context.save()虽然执行了但数据没有发生变化。验证冲突覆盖逻辑。把服务端返回的serverUpdatedAt改成一个比本地更早的时间再调用一次同步。预期本地数据不会被覆盖因为你的代码里已经加了existingUpdatedAt snapshot.serverUpdatedAt的判断。这个设计避免了设备时间回拨或者服务端数据滞后时把新数据冲掉。验证断网场景。启动模拟器把 Mac 的 Wi-Fi 关闭直接在本地写一条数据然后恢复网络触发同步。预期流程是断网时本地 UI 可以正常显示旧数据恢复网络后同步服务把服务器上的最新数据拉回来。如果服务器暂时不可用本地数据不会丢失下次同步会继续尝试。如果同步没有触发第一步检查BGTaskSchedulerPermittedIdentifiers是否写错。第二步检查模拟器是否支持后台刷新模拟器经常需要手动触发在 Xcode 菜单中执行 Debug - Simulate Background Fetch。第三步检查代码里是否真的调用了register()和schedule()这两个方法缺一不可。7. 常见问题与排查思路在本地优先同步开发中常见问题和排查方式可以汇总成下面这张表方便后续遇到问题时快速定位。问题现象可能原因排查方式解决方案同步后金额重复累加没有检查幂等键查看本地 lastSyncedId 是否每次相同在写入前判断 syncId并保证服务端返回唯一 ID同步后数据被旧版本覆盖没有比较时间或版本号检查服务端和本地的时间戳更新时间戳比较逻辑或改用版本号递增跨线程访问 Core Data 崩溃在主上下文之外的线程直接使用主上下文对象加断点查看调用线程检查 Crash 日志使用 newBackgroundContext() 新建上下文后台同步一直不执行Info.plist 缺少后台任务权限查看系统日志和崩溃报告补全 BGTaskSchedulerPermittedIdentifiers模拟器无法模拟断网模拟器本身没有飞行模式使用 macOS 断网或使用 Network Link Conditioner参考官方工具模拟弱网旧 Vesper 源码无法编译使用 Xcode 新版本但代码基于旧 SDK查看编译错误中废弃 API 提示不直接运行旧代码只参照设计思路服务端时间不准导致数据冲突服务器和客户端时钟差异太大输出两个时间并对比不依赖时间戳改用单调递增版本号最容易被忽略的一个坑是updatedAt比较基于时间戳但在分布式系统里不同服务器的时钟不一定完全同步。如果你的项目涉及跨地域部署更稳妥的做法是给每条快照增加一个单调递增的 version 字段。版本号冲突时谁的 version 大谁的数据就生效。这个方案比时间戳更可靠。另一个容易踩的坑是不要在多个线程里共享同一个NSManagedObjectContext。Core Data 的所有托管对象都和创建它的上下文绑定跨线程读取会导致各种诡异的 EXC_BAD_ACCESS 崩溃。解决方法是每次后台导入都使用container.newBackgroundContext()并且在performAndWait内部完成数据修改。8. 最佳实践与工程建议如果你准备把这套同步模型用到自己项目里有几个工程层面的建议值得提前想清楚。第一命名要体现同步语义。不要在实体里只放一个balance字段建议加上updatedAt、lastSyncedId、isDirty这样的同步字段。isDirty表示本地是否有没有上传的修改这对增量同步特别重要。命名规范一旦在项目初期定好后期加功能会轻松很多。第二把服务端接口设计成幂等的。客户端可以重试但服务端必须能识别重复请求。常见做法是要求客户端每次请求带一个全局唯一的 syncId服务端用一个去重表保存已处理过的 ID。当重复请求到达时直接返回上次的结果而不是重新执行业务逻辑。水晶累加这类场景幂等尤其重要因为一次请求重试导致水晶翻倍用户投诉几乎不可避免。第三给每个托管对象增加一个同步状态字段例如pendingSync、synced、syncFailed。本地写入后立即标记为pendingSync同步成功后改为synced失败则保留pendingSync并记录错误次数。这样你在做调试时可以快速筛选出哪些数据还没同步。第四日志要多打。每次同步开始、结束、跳过、冲突都要记录关键字段。不建议只记success或failure至少要把 accountId、syncId、本地时间、服务端时间、最终生效值打出来。CSDN 读者如果在生产环境排查问题第一件事永远是看日志而不是看 UI 表现。第五不要在 App 启动时就发起大量同步请求。一个常见的错误是在applicationDidFinishLaunching里直接 for 循环调用同步。更好的做法是等 UI 空闲后一次性同步并且带上频率限制。后台任务同样要遵守系统限制长时间占用网络会被系统判定为滥用反而降低任务的执行优先级。第六注意安全边界。如果你的应用涉及账号体系服务端接口一定要做身份认证和权限校验。不要因为只是为了同步一个水晶数量就省略掉 token 校验。涉及用户数据的操作都应该遵循最小权限原则不要请求与业务无关的权限不要存储不必要的敏感信息。另外提醒一句游戏外挂、自动点击、绕过系统或游戏规则的行为存在账号封禁和合规风险本文只讨论正规的开发者数据同步不提供任何此类方案。第七升级 Core Data 模型时要使用轻量迁移。给实体新增字段时可以在模型编辑器中设置默认值然后使用自动迁移。如果模型变化比较大建议在测试环境先验证迁移路径避免用户升级 App 后 Core Data 打不开。9. 总结与后续学习方向这篇文章通过在布吉岛打水晶这个场景把 Vesper 项目里最核心的本地优先同步思想迁移了过来。你真正应该带走的不是某一段代码而是三个工程判断UI 优先读本地库写入优先落本地库同步由后台任务统一驱动每次同步都要有幂等键防止重复执行冲突解决要有明确规则优先用版本号其次才是时间戳。接下来的实践路径可以这样安排先用本文的示例工程跑通正常同步和幂等验证然后试着把服务器返回的 JSON 换成你项目的真实接口加上认证参数再往后可以研究 Core Data 的派生数据、NSBatchInsertRequest 批量导入以及 CloudKit 的同步方案它们会进一步降低你处理同步问题的工作量。真正的工程能力往往就是从这样一个看似小题大做的同步器里积累出来的。下次再遇到数据对不上、重复累加、断网丢数据的问题你可以少走很多弯路。建议先把这篇文章收藏起来等真需要设计同步模块时照着这个思路动手验证一遍。