我和 CloudKit 的这八年：从开源 IceCream 到商业应用实战

其实最早接触 CloudKit，要追溯到 2017 年。那时我刚毕业，还在南京扇贝网做一名 iOS 工程师。那一年，移动互联网浪潮依然翻涌，iOS、Android 以及跨平台开发技术正如火如荼地发展，各路大咖活跃在微博等平台上分享最新技术。

当时我们公司的 iOS 小组虽然只有 5 个人，但技术氛围非常好。小组长跟我们说：“每周五下午我们不写需求，专门交流学习 iOS 的新技术，PM 那边做不完的需求我来挡。”

刚毕业的我如旱逢甘霖，像海绵一样非常期待每周的组内充电时间。

在一次周五分享会上，我展示了一个 iOS Side Project（一个名为“小目标”的类 To-Do List 量化目标软件，现已下架），并演示了我是如何使用 CloudKit 丝滑同步用户本地数据的。

组长听完分享后鼓励我：“你可以把这个本地数据一键加上 iCloud 同步功能的部分抽离出来，专门做成一个开源库，应该有搞头。”

于是，我大概花了两个周末的时间，将这个功能封装并开源发布在 GitHub 上，取名为 IceCream。当时的宣传口号是：“在项目里仅需添加一行代码，就可以让你的 Realm 数据库实现在 iCloud 上同步”。

发完项目后，我专门发了条 Twitter。

好家伙，不发不知道，发完一下子在网络上传播开了。很多开发者 Star 了我的项目，那条推特也被 Peter Steinberger 转发。一时间大家都在讨论 IceCream，项目很快收获了成百上千个有机且健康的 Star，大家也提交了很多 PR。我也是从这个时候开始，被更多的开发者所认识。（到现在我还记得，下班后半夜在出租屋里打开电脑，看到项目被不断转发讨论时，敲键盘时那双战战兢兢的手。笑：）

逐渐地，IceCream 被越来越多的开发者应用在个人甚至公司的 App 里。那段时间我也十分积极，业余时间几乎都花在了回复邮件和维护项目上。故事的高潮发生在 2018 年 9 月左右，我收到了一封来自 Cupertino 的邮件——IceCream 得到了 Apple CloudKit 官方团队的肯定。

这甚至为我带来了机会。2019 年，借由公司外派去圣何塞参加 WWDC 的契机，我与 CloudKit 团队成员面对面进行了非常愉快的交流。

IceCream 项目从诞生起一直是用业余时间维护的（最近几年更新频率有所下降，如果大家需求还很大，我会重新捡起来维护 😄）。在这个过程中，我对 CloudKit 的方方面面、边边角角都有了非常细致的了解，大大小小的坑也都踩了一遍。

IceCream 与 CKSyncEngine

这里有一个好玩的故事。IceCream 诞生于 2017 年，从第一版开始，我就将其核心管理类命名为 SyncEngine。直到 2023 年，Apple 官方推出了 CKSyncEngine，其很多接口定义与 IceCream 惊人地相似。在某种程度上，这对我来说也算是一种官方的“认可”。

不过，两者的设计理念有所不同。IceCream 是针对 Realm 数据库的完整封装，可以直接调用；而 CKSyncEngine 则要求开发者对本地持久层比较熟悉，并在 API 中自行适配。

举个例子，在 IceCream 里，核心逻辑是通过持有 NotificationToken 来监听 Realm 的变化，从而自动在后台执行 CloudKit 同步：

BackgroundWorker.shared.start {
    let realm = try! Realm()
    // 监听 Realm 变化
    self.notificationToken = realm.objects(T.self).observe({ [weak self] (changes) in
        guard let self = self else { return }
        switch changes {
        case .initial(_):
            break
        case .update(let collection, _, let insertions, let modifications):
            // 筛选并转换需要同步的数据
            let recordsToStore = (insertions + modifications)
                .filter { $0 < collection.count }
                .map { collection[$0] }
                .map { $0.record }
            let recordIDsToDelete = modifications
                .filter { $0 < collection.count }
                .map { collection[$0] }
                .map { $0.recordID }
            
            guard !recordsToStore.isEmpty || !recordIDsToDelete.isEmpty else { return }
            self.pipeToEngine?(recordsToStore, recordIDsToDelete)
        case .error(_):
            break
        }
    })
}

而在 Apple 的 CKSyncEngine 中，你需要自行追踪本地数据库的变化，然后通过 add(pendingDatabaseChanges:) 和 add(pendingRecordZoneChanges:) 方法，告知引擎在下一次同步时上传哪些变更。

简单来说，如果你在使用 Realm，IceCream 依然是“一行代码实现同步”的最佳选择；如果你使用 SQLite、Core Data 或其他存储方式，或者希望拥有更高的灵活性，那么 CKSyncEngine 是一个强大的工具。（注：CKSyncEngine 需要 iOS 17+，而 IceCream 支持低至 iOS 10 😆）。

时至今日，IceCream 诞生已 8 年，依然是 GitHub 上 CloudKit 标签下最热门的开源项目之一。

为什么选择 CloudKit？

CloudKit 之所以在开发者中如此受欢迎，原因无非以下几点：

1. 免费。
2. 不算你的容量：在 Private Database 同步的数据，占用的是用户自己的 iCloud 空间配额。
3. 配置简单：客户端驱动（Client-driven），特别适合没有服务端开发经验的 iOS 工程师。
4. 核心卖点：虽然 Apple 并不建议这样做，但在 App 中提供“iCloud 同步”已成为许多应用的核心付费点。

关于免费，Craig Federighi 在 WWDC 上曾说过一句经典的话：“CloudKit is effectively free…with limits.”

虽然早期那张详细的 Limits 图表在官网找不到了，但这么多年来，我从未听说周围有开发者需要给 CloudKit 付费。Apple 的初衷是希望开发者使用 CloudKit，只要不滥用（Abuse）即可。

此外，尽管常有开发者吐槽 iCloud 不稳定，但对我这样一个不熟悉服务器运维的开发者来说，CloudKit 如获至宝。系统自带的备忘录、iCloud Drive 都基于此，足以证明其可靠性。在我的实际体验中，iCloud 服务一直非常稳定。

CloudKit 的局限与避坑

肘子哥（Fatbobman）特意让我聊聊 CloudKit 的局限性。结合多年的项目经验，我认为以下几点值得注意：

1. 访问速度有限

如果你通过 CKQueryOperation 请求较多数据（例如超过一页 100 条），完成时间会显著变长。我做过实验，请求 Public Database 里最近更新的 1000 条数据，全部拉取完大约需要 10 秒。

对于成熟的商业项目，这个时长通常无法接受。因此，前端必须做好足够的加载优化：

• 大多数时候，不必等待所有数据加载完毕再展示。可以采取“按需取用”的策略，先加载前几条数据供用户消费，后台持续请求并缓存剩余数据。这与 App 启动优化理念一致：延迟加载或懒加载（Lazy Load）。

• 另外，对于图片、视频等大文件，CloudKit 提供的配置有限（无 CDN 加速等），比较黑盒。对于大文件同步，建议配合 iCloud Documents 或其他专业云存储服务。

2. 无法进行 Count 等聚合操作

这是 CloudKit 目前较大的一个短板：你无法快速获取“符合 xxx 条件的总人数”。

目前的规避办法是：另起一个专门的服务（例如在服务器上运行脚本），定期轮询或监听 CloudKit 数据的变化，计算好数值后存回，客户端有需求时直接读取或访问该服务。如果有小伙伴有更好的纯 CloudKit 实现方法，欢迎交流。

3. 生产环境 Schema 无法回滚

CloudKit Console 分为 Development 和 Production 两个环境。 注意：一旦将 Schema 部署到生产环境（Deploy to Production），字段只能增，不能减，也不能改类型。 这与肘子哥之前文章中提到的原则一致。

如果云端有一个废弃字段怎么办？我的办法是 不处理 😆。让它作为“冗余”字段留在那里，只需在客户端 Model 解析时将其设为 Optional，并不再在业务代码中使用即可：

// Deprecated field handling
let emailAddress = record.value(forKey: "emailAddress") as? String ?? ""

这对开发者设计数据表的前瞻性以及软件工程水平提出了较高要求。

Music Mate 实战：如何“薅” CloudKit 羊毛

2022 年 2 月，我上线了一款音乐交友 App —— Music Mate。其核心功能是通过上下滑手势“偷看”别人正在听的歌，遇到品味相同的可以开启聊天或查看社交账号。

从内测版开始，我就一直使用 CloudKit Public Database 作为云端数据存储。配合 SwiftUI，体验非常不错。

典型查询场景

CloudKit 能够很好地满足“听歌交友”业务中的特定查询需求：

1. 展示正在和你听同一首歌的朋友 这是核心功能，简化后的 Query 写法如下：

let musicItemID = "1435933839" // 当前歌曲 ID
let predicate = NSPredicate(format: "musicItemID == %@", musicItemID)
let query = CKQuery(recordType: "FriendAnnotation", predicate: predicate)
query.sortDescriptors = [
    NSSortDescriptor(key: "modificationDate", ascending: false)
]

let operation = CKQueryOperation(query: query)
operation.recordMatchedBlock = { [weak self] recordID, result in
    self?.resolveRecordResult(recordID: recordID, result: result)
}
operation.queryResultBlock = { [weak self] result in
    self?.resolveResult(result: result)
}
container.publicCloudDatabase.add(operation)

2. 展示附近 10km 内听歌的朋友

let currentLocation = CLLocation(latitude: 31, longitude: 121.51)
// 使用 CloudKit 特有的 distanceToLocation 函数
let predicate = NSPredicate(format: "distanceToLocation:fromLocation:(location, %@) < %f", currentLocation, 10000)

3. 其他筛选 如只展示绑定了 Instagram/小红书的用户，或按性别筛选等。

Music Mate 上线三年多，经历过单日全球涌入 3 万多新用户的高峰，CloudKit 服务一次都没有崩过，非常让人安心。

同时，Music Mate 用户的“收藏歌曲列表”是通过 IceCream 在 Private Database 进行同步的。上线至今，几乎没有收到过用户反馈数据丢失或同步出错的问题。

小插曲：Music Mate 中“xxx 播放了你在听的歌”的通知，实际上是使用第三方 IM SDK 走的 APNs，而非 CloudKit Subscription。虽然我没深用 Subscription，但 CKQuerySubscription 是一个潜力巨大的功能，值得大家探索。

CloudKit 的进阶玩法

除了常规的数据存储与同步，我还挖掘了一些 CloudKit 的其他用法。

1. 后台动态开关 (Feature Flags)

在业务中，我们常需要 Feature Flag 来进行 A/B 测试或开启特定模式。通过 CloudKit Public Database 建立一张配置表，可以快速搭建一套远程配置系统，无需额外部署后端。

2. 跨 App 访问云端数据 (Cross-App Access)

这是一个比较冷门但强大的功能。同一个开发者账号下的不同 App，不仅可以访问自己的 Container，还可以互相访问彼此的 Container。

比如，我最近上线了一款帮助预习演唱会歌单的 App —— Setlists。在歌单详情页，用户可以看到每首歌当前有多少人（在 Music Mate 中）正在听。这个数据就是 Setlists 客户端直接请求 Music Mate 的 Public Database 获取的。

实现步骤：

1. 在 Setlists Xcode 项目的 Signing & Capabilities 中，勾选 Music Mate 的 iCloud Container。

2. 代码中指定 Container ID：

// 在 Setlists App 中访问 Music Mate 的容器
private let container = CKContainer(identifier: "iCloud.reversed-domain.xxx.musicmate")
let operation = CKQueryOperation(query: query)
container.publicCloudDatabase.add(operation)

这样就轻松实现了跨应用的数据共享生态。

总结

以上就是我使用 CloudKit 这些年的一些心得。在 Apple 的技术框架中，有很多像 CloudKit 这样功能强大但容易被忽视的 “Hidden Gems”（宝藏），需要我们去慢慢淘沙发掘。

希望这篇文章能起到抛砖引玉的作用。如果大家对 CloudKit 有更多使用心得，欢迎通过各种方式与我交流、分享。