CloudKit入门篇：CloudKit 基础

发布于 · 2026-09-12 · # CloudKit # CloudKit

入门篇：CloudKit 基础
本篇概述
本篇是 CloudKit 全栈教程的第一站。我们将从最基本的问题出发——CloudKit 到底是什么、它解决了什么问题——然后逐步建立对 CloudKit 数据模型的完整认知，完成环境配置，掌握增删改查与查询操作，最后用一个可运行的 iCloud 笔记应用把所有知识点串联起来。完成本篇后，你将能够独立使用 CloudKit 在自己的 app 中实现 iCloud 数据存储与跨设备同步。

CloudKit 是什么
1.1 用类比理解 CloudKit 的定位
很多初学者第一次接触 CloudKit 时，会把它和 Core Data、SwiftData、Realm 这类本地数据库混淆，以为 CloudKit 是"又一个数据库框架"。这个理解是错的。
我们可以把 CloudKit 类比为一套快递服务。你的 app 里原本就已经有了自己的"仓库"——可能是 SwiftData、Core Data，或者只是一个内存里的数组。CloudKit 并不关心你的本地仓库长什么样，它的职责是充当 app 和 iCloud 服务器之间的快递员：你把要同步的数据打包交给它，它负责把包裹送到 iCloud；反过来，iCloud 上有新数据时，它也会把包裹取回来交给你。
换句话说，CloudKit 不是替代本地数据库的方案，而是负责在 app 和 iCloud 服务器之间搬运数据的"快递服务"。你的 app 是寄件人也是收件人，iCloud 是中转站和长期仓库，CloudKit 框架则是那辆来回奔波的快递车。
这种定位决定了 CloudKit 的工作方式是客户端驱动的：所有数据操作的发起方都是 app（客户端），CloudKit 不会主动把数据塞给你，而是等你下单（调用 API）才去取件。这也意味着你需要自己处理"什么时候该同步""同步哪些数据"这类逻辑，CloudKit 只负责忠实执行你的指令。
1.2 CloudKit 的优势
CloudKit 相比第三方 BaaS（Backend as a Service）或自建后端，有几个非常突出的优势。
第一，免费且不占用开发者容量。CloudKit 对开发者完全免费，没有按请求次数计费、没有按存储量阶梯收费的烦恼。更关键的是，用户存储在 Private Database（私有数据库）里的数据，占用的是用户自己的 iCloud 存储空间，而不是开发者的配额。这意味着你的 app 用户越多，CloudKit 反而越"划算"，因为你不需要为用户的存储买单。
第二，配置简单。你不需要搭建服务器、配置数据库、编写 API 接口、管理 HTTPS 证书。在 Xcode 里勾选一个能力、填一个 Container ID，基本就完成了。对个人开发者和小团队来说，这意味着可以省下大量后端运维成本。
第三，天然集成 Apple 生态。CloudKit 和 iCloud 账户深度绑定，用户不需要在你的 app 里再注册一个账号密码。只要用户在系统设置里登录了 iCloud，你的 app 就能直接拿到身份信息，实现"无感登录"。数据也会跟随用户的 iCloud 账户在 iPhone、iPad、Mac 之间自动同步。
第四，客户端驱动，学习曲线可控。CloudKit 的 API 设计是面向客户端开发者的，全部用 Swift（或 Objective-C）调用，和写本地代码的体验接近，不需要学习额外的后端语言或框架。
1.3 适用场景与不适用场景
CloudKit 适合的场景包括：需要在用户多设备间同步个人数据（如笔记、待办、书签、个人收藏）；需要跨用户共享少量数据（如协作清单、共享相册）；需要给用户提供"备份恢复"能力（如把用户配置同步到 iCloud）；以及希望以最低成本为 app 增加"云端"属性的场景。
CloudKit 不适合的场景包括：需要服务端主动推送数据给客户端的实时场景（CloudKit 的订阅机制可以做推送，但实时性和灵活性不如专门的推送服务）；需要复杂的服务端业务逻辑（如订单处理、支付、推荐算法）——CloudKit 是数据搬运工，不是业务逻辑执行者；需要支持非 Apple 平台（Android、Web）的场景——CloudKit 提供了 Web Services API，但体验远不如原生 SDK，且需要额外鉴权处理；以及需要海量用户共享同一份数据的高并发读取场景——Public Database 的查询性能有限（实测 1000 条记录约需 10 秒），不适合做高并发的公共数据源。
理解了这些边界后，你就能判断自己的需求是否适合用 CloudKit，而不是把所有"需要联网"的功能都套在它身上。

核心概念
CloudKit 的数据模型由若干层级的概念组成，从大到小依次是 Container、Database、RecordZone、Record。在深入代码之前，我们必须先把这些概念及其关系理清楚，否则后面的 API 调用会让人摸不着头脑。本节每个概念都会给出类比定义。
2.1 CKContainer（容器）
CKContainer 是 CloudKit 中所有数据的顶层容器，你可以把它类比为一栋大楼。这栋大楼属于你的 app，大楼里存放着这个 app 在 iCloud 上的全部数据。每个 app 通常对应一个 Container，Container 之间是相互隔离的——A app 的大楼里看不到 B app 大楼里的东西。
每个 Container 都有一个唯一标识符，采用反向 DNS 格式命名，形如 iCloud.com.example.myapp。这个标识符在创建时就固定下来，整个 app 生命周期内通过它来找到自己的"大楼"。你在 Xcode 里创建 Container 时填入的名字，最终会拼成这样一个标识。
在代码里获取默认容器只需要一行：
// 获取当前 app 的默认容器
// 类比：找到属于你这个 app 的那栋大楼
let container = CKContainer.default()

2.2 CKDatabase（数据库）
如果说 Container 是一栋大楼，那么 CKDatabase 就是大楼里不同的房间，每个房间承担不同用途。一个 Container 固定包含三个数据库，它们各司其职：
Private Database（私有数据库）：存放用户个人的私密数据。只有用户自己能访问这些数据，连开发者都看不到。类比为大楼里"只对你本人开放的个人储物间"。比如你的笔记内容、你的收藏夹，都应该放在这里。
Public Database（公共数据库）：存放所有用户共享的公开数据。所有用户都能读取，通常用于存放 app 的公共内容，比如应用内的公告、公共图鉴、模板库等。类比为大楼里的"公共展厅"，所有人都能进去看。
Shared Database（共享数据库）：存放用户之间互相分享的数据。当一个用户把自己的某些数据分享给另一个用户时，这些数据会出现在接收方的 Shared Database 里。类比为大楼里的"共享会议室"，只有被邀请的人才能进来。
需要特别注意的是，Private Database 里的数据永远不会自动跑到 Public Database。数据放在哪个房间，完全由你的代码决定。这就要求你在设计数据模型时就想清楚：哪些是私有的，哪些是公开的，哪些需要分享。下面的代码展示了如何拿到这三种数据库的引用：
let container = CKContainer.default()

// 类比：进入大楼里只属于你个人的储物间
let privateDB = container.privateCloudDatabase

// 类比：进入大楼的公共展厅
let publicDB = container.publicCloudDatabase

// 类比：进入别人邀请你去的共享会议室
let sharedDB = container.sharedCloudDatabase

2.3 CKRecord（记录）
CKRecord 是 CloudKit 中数据的基本单位，你可以把它类比为一张数据卡片。每张卡片上可以写若干项内容，每一项就是一个键值对（key-value）。你想保存一条笔记、一个任务、一张图片的元信息，最终在 CloudKit 里都对应一张 CKRecord。
CKRecord 本质上是键值对的集合，这点和字典很像，但它还承载了额外的元信息：记录类型、记录 ID、修改时间、创建时间等。这些元信息由 CloudKit 自动维护，你通常不需要手动设置。
2.4 RecordType（记录类型）
如果说 CKRecord 是一张具体的数据卡片，那么 RecordType（记录类型）就是这张卡片的模板。类比为不同的"表单类型"：你填一张"笔记表单"和一张"任务表单"，用的模板是不一样的。
RecordType 是一个字符串，比如 "Note"、"Task"、"Reminder"。同一个 RecordType 下的记录通常拥有相同结构的字段。创建记录时必须指定 RecordType：
// 创建一张"笔记"类型的数据卡片
// 类比：拿一张空白的笔记表单准备填写
let noteRecord = CKRecord(recordType: "Note")

注意，CloudKit 是**无模式（schemaless）**的——你不需要像传统数据库那样先建表、定义列。第一次往某个 RecordType 里写字段时，CloudKit 会自动"学到"这个结构。不过为了避免混乱，建议你在代码里统一管理 RecordType 和字段名，最好用常量定义。
2.5 CKRecordZone（记录区域）
CKRecordZone 是数据库内对记录进行逻辑分组的机制，你可以把它类比为大房间里的隔间。一个 Database 里默认就有一个"默认区域"（Default Zone），你也可以创建自定义区域（Custom Zone）来把相关记录圈在一起。
为什么需要区域？因为某些高级功能是以区域为单位的，比如事务（一个区域内的多条记录可以原子性地一起提交）、共享（你可以把整个自定义区域分享给别的用户）、批量操作的局部性优化。对于入门场景，绝大多数操作都在默认区域里进行，你暂时不用关心自定义区域。
// 获取私有数据库的默认区域 ID
// 类比：默认隔间的门牌号
let defaultZoneID = CKRecordZone.default().zoneID

2.6 CKRecord.ID（记录标识）
每条记录都有一个全局唯一的标识符 CKRecord.ID。它由两部分组成：recordName（记录名，一个字符串）和 zoneID（所属区域 ID）。类比为数据卡片上的"条形码"，通过它可以在茫茫记录中精确定位到某一张。
如果不手动指定 recordName，CloudKit 会自动生成一个 UUID 作为记录名。当你需要根据 ID 取回某条特定记录时，就要用到这个标识。
// 用一个字符串名创建记录 ID（位于默认区域）
// 类比：给数据卡片贴上一个唯一条形码
let recordID = CKRecord.ID(recordName: "note-001")

2.7 Field（字段）
Field 是 CKRecord 里的键值对，也就是数据卡片上填写的每一项内容。每一个字段由一个键名和一个值组成。CloudKit 支持的字段值类型包括：String、Int、Double、Bool、Date、Data（二进制）、CLLocation（地理位置）、CKReference（指向另一条记录的引用）、CKAsset（大文件引用，存在 iCloud 文件存储里）以及这些类型的数组版本。
设置字段值时，需要把值转换成 CKRecordValue 类型，这是所有可存储类型共同遵循的协议：
let noteRecord = CKRecord(recordType: "Note")

// 设置字段值，注意必须用 as CKRecordValue 进行类型转换
// 类比：在数据卡片的对应栏目里填写内容
noteRecord["title"] = "我的第一篇笔记" as CKRecordValue
noteRecord["content"] = "Hello CloudKit!" as CKRecordValue
noteRecord["createdAt"] = Date() as CKRecordValue
noteRecord["wordCount"] = 2 as CKRecordValue

// 读取字段值时，由于返回的是可选的 CKRecordValue，需要再转回具体类型
if let title = noteRecord["title"] as? String {
    print("标题: \(title)")
}

// 注意： 类型转换是初学者最容易踩坑的地方。CloudKit 存储的值会作为 CKRecordValue（实际上是 __CKRecordValue，一组基础类型的协议）返回，读取时一定要用 as? 安全转换回你期望的具体类型，否则运行时类型不匹配会得到 nil。

架构关系图
把上面这些概念组合起来，CloudKit 的数据层级关系如下所示。从 Container 到 Record 是逐层包含的关系：
┌──────────────────────────────────────────────────────────────────┐
│                         CKContainer                               │
│                   iCloud.com.example.myapp                        │
│                          (一栋大楼)                                │
│                                                                   │
│   ┌────────────────────┐  ┌────────────────────┐  ┌────────────┐ │
│   │  Private Database  │  │  Public Database   │  │  Shared    │ │
│   │   (个人储物间)      │  │   (公共展厅)        │  │  Database  │ │
│   │                    │  │                    │  │ (共享会议室)│ │
│   │  ┌───────────────┐ │  │  ┌───────────────┐ │  └────────────┘ │
│   │  │  RecordZone   │ │  │  │  RecordZone   │ │                  │
│   │  │  (隔间)       │ │  │  │  (隔间)       │ │                  │
│   │  │               │ │  │  │               │ │                  │
│   │  │ ┌───────────┐ │ │  │  │ ┌───────────┐ │ │                  │
│   │  │ │  Record   │ │ │  │  │ │  Record   │ │ │                  │
│   │  │ │ Note: ... │ │ │  │  │ │ Item: ...│ │ │                  │
│   │  │ │ Field=值  │ │ │  │  │ │ Field=值  │ │ │                  │
│   │  │ └───────────┘ │ │  │  │ └───────────┘ │ │                  │
│   │  └───────────────┘ │  │  └───────────────┘ │                  │
│   └────────────────────┘  └────────────────────┘                  │
└──────────────────────────────────────────────────────────────────┘

记住这条从大到小的链路：Container → Database → RecordZone → Record → Field。后面所有的 API 调用，本质上都是沿着这条链路找到目标位置，然后执行操作。

环境配置
在写任何 CloudKit 代码之前，必须先在 Xcode 里完成能力配置。这一步如果漏掉，代码会编译通过但运行时报错，因为 app 没有访问 iCloud 的权限。
4.1 添加 iCloud 能力
打开你的 Xcode 项目，选中顶部的项目导航器中的 app Target，切换到 Signing & Capabilities 标签页。点击左上角的 + Capability 按钮，在弹出列表中搜索 "iCloud"，双击添加。添加后你会看到 iCloud 能力面板，里面有几项可勾选的服务，请勾选 CloudKit。
4.2 创建 CloudKit Container
勾选 CloudKit 后，面板里会出现 Container 管理 区域。如果你的项目还没有 Container，点击 + 按钮（或 None 旁边的添加），在弹窗中输入标识符。一般约定用反向 DNS 格式，Xcode 会自动帮你补全前缀，最终形如 iCloud.com.example.myapp。
// 注意： Container 标识符一旦确定并发布到生产环境后，就不应再改动。因为它会被写入 entitlements 文件，作为 app 身份的一部分被 Apple 服务器识别。改了 Container 等于换了一栋新大楼，原来大楼里的数据就找不到了。
4.3 配置 entitlements 文件
完成上述操作后，Xcode 会自动在你的项目里生成（或更新）一个 <AppName>.entitlements 文件，里面会包含类似这样的键值：
<key>com.apple.developer.icloud-container-identifiers</key>
<array>
    <string>iCloud.com.example.myapp</string>
</array>
<key>com.apple.developer.icloud-services</key>
<array>
    <string>CloudKit</string>
</array>

这个文件描述了 app 被授予的 iCloud 权限。正常情况下你不需要手动编辑它，Xcode 会在能力面板里同步维护。但如果你遇到"找不到 Container"或"无权限"的运行时错误，第一时间检查这个文件是否正确包含了你的 Container ID。
4.4 Development 与 Production 环境的区别
CloudKit 有两套环境：Development（开发环境） 和 Production（生产环境）。
在开发阶段，通过 Xcode 直接安装到你设备上的 app 使用的是 Development 环境。这个环境里的数据只有你自己能看到，方便你随便增删测试，不会影响真实用户。当你的 app 通过 App Store 发布（或用 TestFlight 分发）后，使用的就是 Production 环境，真实用户的数据都在这里。
两套环境的数据是完全隔离的，RecordType 的结构（schema）也是独立的。也就是说，你在 Development 环境里创建的 RecordType 和测试数据，Production 环境里看不到，反之亦然。当你修改了 schema（比如新增字段）并准备上线前，需要通过 CloudKit Dashboard 的 "Deploy Schema Changes to Production" 把结构变更部署到生产环境。
获取默认容器的代码在两个环境里是同一行，系统会根据 app 的分发方式自动选择对应环境：
// 无论开发还是生产环境，都用同一行代码获取默认容器
// 类比：系统会自动把你带去当前对应的那栋大楼
let container = CKContainer.default()

你也可以在浏览器访问 CloudKit Dashboard 来可视化查看两个环境里的数据、RecordType 结构、订阅、用户等信息，这是调试 CloudKit 问题最常用的工具。

基础 CRUD 操作
CRUD 是 Create（创建）、Read（读取）、Update（更新）、Delete（删除）的缩写，是任何数据存储方案最核心的四类操作。本节我们用一个"笔记 app"的场景，逐一演示 CloudKit 的 CRUD 实现。所有操作都以 Private Database 为例，因为这是最常用的场景。
5.1 创建记录
应用场景：用户在你的笔记 app 中新建了一条笔记，需要保存到 iCloud，以便在其他设备上也能看到。
创建记录分三步：先实例化一个 CKRecord 并指定 RecordType；然后逐个设置字段值；最后调用数据库的 save 方法把记录提交到 iCloud。下面是完整的闭包版本示例：
import CloudKit

func createNote() {
    // 创建一条笔记记录
    // 类比：拿一张空白的笔记表单，准备填写
    let noteRecord = CKRecord(recordType: "Note")

// 逐项填写字段，注意必须用 as CKRecordValue 进行类型转换
    noteRecord["title"] = "我的第一篇笔记" as CKRecordValue
    noteRecord["content"] = "Hello CloudKit!" as CKRecordValue
    noteRecord["createdAt"] = Date() as CKRecordValue

// 获取默认容器，再拿到私有数据库
    // 类比：找到大楼，进入你的个人储物间
    let container = CKContainer.default()
    let privateDB = container.privateCloudDatabase

// 把记录保存到私有数据库
    // 类比：把填好的卡片放进储物间
    privateDB.save(noteRecord) { record, error in
        if let error = error {
            print("保存失败: \(error)")
        } else {
            // 注意：成功回调里返回的 record 拥有服务器分配的 recordID
            print("保存成功: \(record?.recordID.recordName ?? "")")
        }
    }
}

// 注意： 没有手动指定 recordName 时，CloudKit 会自动生成一个 UUID 作为记录名。如果你需要在保存前就知道 ID（例如做本地缓存关联），可以自己创建带 recordName 的 CKRecord.ID，再用 CKRecord(recordType:recordID:) 初始化记录。
5.2 读取记录
应用场景：用户打开了某条历史笔记，app 需要根据记录 ID 从 iCloud 取回这条笔记的完整内容。
CloudKit 提供了基于闭包的传统 API 和基于 async/await 的现代 API 两套接口。在现代 Swift 项目中，推荐使用 async/await 版本，代码更线性、更易读。下面同时展示两种写法。
闭包版本：
func fetchNote(recordID: CKRecord.ID) {
    let container = CKContainer.default()
    let privateDB = container.privateCloudDatabase

// 根据记录 ID 获取单条记录
    // 类比：凭条形码从储物间取出指定卡片
    privateDB.fetch(withRecordID: recordID) { record, error in
        if let error = error {
            print("获取失败: \(error)")
            return
        }
        guard let note = record else { return }
        // 读取字段值，注意用 as? 安全转换回具体类型
        let title = note["title"] as? String ?? "（无标题）"
        let content = note["content"] as? String ?? ""
        print("标题: \(title)，内容: \(content)")
    }
}

async/await 版本（推荐）：
func fetchNoteAsync(recordID: CKRecord.ID) async {
    let container = CKContainer.default()
    let privateDB = container.privateCloudDatabase

do {
        // async 版本的 fetch，返回值就是 CKRecord
        // 类比：await 等待快递员把卡片取回来
        let note = try await privateDB.record(for: recordID)
        let title = note["title"] as? String ?? "（无标题）"
        let content = note["content"] as? String ?? ""
        print("标题: \(title)，内容: \(content)")
    } catch {
        print("获取失败: \(error)")
    }
}

// 注意： async/await 版本的 record(for:) 是 iOS 15+ 引入的 API。本教程基于 iOS 17+，可以放心使用。如果读取的记录不存在，会抛出 CKError.recordNotFound 错误，记得在 catch 里处理这种情况。
5.3 修改记录
应用场景：用户编辑了一条已有笔记的内容，点击保存后，需要把更新同步到 iCloud。
修改记录的关键点在于：CloudKit 里更新和创建用的是同一个 save 方法。这是因为 CloudKit 会根据传入的 CKRecord 是否带有服务器已知的 recordID 来判断是新增还是更新。如果这个 recordID 在服务器上已存在，save 就执行更新；如果不存在，就执行新增。所以修改记录的流程是：先读取（或持有）已有记录，修改字段，再 save。
func updateNote(_ note: CKRecord, newContent: String) async {
    let container = CKContainer.default()
    let privateDB = container.privateCloudDatabase

// 直接修改已有记录的字段
    // 类比：在卡片上擦掉旧内容，写上新内容
    note["content"] = newContent as CKRecordValue
    note["modifiedAt"] = Date() as CKRecordValue

do {
        // 注意：更新也是调用 save，CloudKit 根据 recordID 判断是新增还是更新
        let saved = try await privateDB.save(note)
        print("更新成功: \(saved.recordID.recordName)")
    } catch {
        // 常见错误：CKError.serverRecordChanged，说明记录已被其他设备改过
        print("更新失败: \(error)")
    }
}

// 注意： 这里有一个重要的并发问题——如果同一张记录在两台设备上同时被修改，后保存的那一方会遇到 CKError.serverRecordChanged（错误码 14）冲突。处理冲突需要用到 CKModifyRecordsOperation 的三个记录数组（保存成功、删除成功、失败），这是中级篇的内容。入门阶段你只需要知道这个错误的存在，并提示用户重试即可。
5.4 删除记录
应用场景：用户在笔记列表里删除了一条笔记，需要从 iCloud 移除该记录，避免它出现在其他设备上。
删除操作通过 CKDatabase.delete 完成，可以按记录 ID 删除，也可以按记录对象删除。下面给出 async/await 版本：
func deleteNote(recordID: CKRecord.ID) async {
    let container = CKContainer.default()
    let privateDB = container.privateCloudDatabase

do {
        // 根据记录 ID 删除记录
        // 类比：把卡片从储物间里取出来扔掉
        let deletedID = try await privateDB.deleteRecord(withID: recordID)
        print("删除成功: \(deletedID.recordName)")
    } catch {
        print("删除失败: \(error)")
    }
}

// 注意： 删除是不可逆操作。一旦记录从 iCloud 删除，所有设备上对应的记录都会消失。如果你的 app 有"回收站"或"撤销"需求，应考虑用"软删除"——即给记录加一个 isDeleted 字段标记为已删除，而不是真正调用 delete，定期再做真正的清理。

查询操作：CKQuery 与 CKQueryOperation
CRUD 里的 Read 只能按记录 ID 取单条记录。但实际需求往往更复杂：用户想看"我的全部笔记""标题里带'重要'的笔记""最近修改的 10 条"。这类按条件检索数据的需求，就要靠查询（Query）来满足。
6.1 CKQuery 基础
应用场景：用户打开笔记列表页，app 需要找出该用户的所有笔记，并按创建时间倒序排列；或者找出标题包含"重要"关键词的笔记。
CKQuery 用来描述一次查询的"条件"和"排序"。它由三部分组成：要查询的 RecordType、筛选条件（NSPredicate）、排序方式（NSSortDescriptor）。
NSPredicate 是 Foundation 的谓词对象，用来表达"满足什么条件的记录才符合要求"。CloudKit 只支持 NSPredicate 的一个子集，下面是常用且被支持的部分：
let container = CKContainer.default()
let privateDB = container.privateCloudDatabase

// 查找标题包含"重要"的笔记
// 注意：CloudKit 只支持 NSPredicate 的部分功能
// 支持的比较运算：== != < <= > >=
// 支持的字符串运算：CONTAINS / BEGINSWITH / ENDSWITH（区分大小写）
// 支持的逻辑运算：AND / OR / NOT（复合谓词）
let predicate = NSPredicate(format: "title CONTAINS %@", "重要")

// 构造查询，指定 RecordType 和谓词
let query = CKQuery(recordType: "Note", predicate: predicate)

// 设置排序：按 createdAt 降序（最新的在前）
query.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]

// 注意： CloudKit 的 NSPredicate 子集有不少限制，初学者务必了解，否则会写出"本地能跑、CloudKit 报错"的谓词：
不支持集合聚合运算（如 @count、@sum、@avg）。
不支持正则匹配（如 MATCHES）。
不支持超过一层深度的 keyPath（如 note.author.name 这种链式访问）。
不支持与 nil 直接比较（如 field == nil），可用 field BEGINSWITH "" 等替代思路。
字符串比较区分大小写，且 CONTAINS 做的是子串匹配而非分词搜索。
只有被标记为 indexable（可查询） 的字段才能用在谓词里，默认在 CloudKit Dashboard 里勾选。
得到 CKQuery 之后，最简单的执行方式是用数据库的便捷 async 方法：
func fetchImportantNotes() async {
    let container = CKContainer.default()
    let privateDB = container.privateCloudDatabase

let predicate = NSPredicate(format: "title CONTAINS %@", "重要")
    let query = CKQuery(recordType: "Note", predicate: predicate)
    query.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]

do {
        // 便捷 async 查询方法，返回匹配结果和游标
        let (results, cursor) = try await privateDB.records(
            matching: query,
            resultsLimit: 100
        )

// results 是 [(CKRecord.ID, Result<CKRecord, Error>)] 数组
        let notes = results.compactMap { _, result in
            try? result.get()
        }
        print("查到 \(notes.count) 条笔记")

// 注意：cursor 不为 nil 表示还有更多匹配记录
        if cursor != nil {
            print("结果超过上限，需要用 cursor 继续翻页")
        }
    } catch {
        print("查询失败: \(error)")
    }
}

6.2 CKQueryOperation
便捷方法适合简单查询，但当需要更细粒度的控制——比如逐条处理记录、限制每页数量、连续翻页——就要用更底层的 CKQueryOperation。
应用场景：分页加载笔记列表，每次加载 50 条，滚到底部再加载下一页；或批量获取大量数据时希望逐条接收，避免一次性占用过多内存。
CKQueryOperation 提供两个核心回调块：
recordMatchedBlock：每匹配到一条记录就回调一次，让你可以逐条处理，参数是 (recordID, Result<CKRecord, Error>)。
queryResultBlock：整个查询结束时回调一次，参数是 Result<CKQueryOperation.Cursor?, Error>，其中的 cursor 用于翻页。
完整的分页查询示例如下，它实现了"一次查一页、查到没有更多为止"的逻辑：
import CloudKit

class NoteFetcher {
    let container = CKContainer.default()
    let privateDB: CKDatabase

init() {
        privateDB = container.privateCloudDatabase
    }

/// 分页查询所有笔记，通过 completion 一次性返回全部结果
    func fetchAllNotes(completion: @escaping ([CKRecord]) -> Void) {
        var allNotes: [CKRecord] = []

// 用"恒真谓词"查出所有 Note 记录
        let predicate = NSPredicate(value: true)
        let query = CKQuery(recordType: "Note", predicate: predicate)
        query.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]

// 从第一页开始查询
        // 类比：从书架第一页开始往后翻
        fetchPage(query: query, cursor: nil, accumulated: &allNotes, completion: completion)
    }

private func fetchPage(
        query: CKQuery?,
        cursor: CKQueryOperation.Cursor?,
        accumulated: inout [CKRecord],
        completion: @escaping ([CKRecord]) -> Void
    ) {
        // 根据是首次查询还是翻页，创建对应的 Operation
        // 注意：首次查询用 query 初始化，翻页用 cursor 初始化
        let operation: CKQueryOperation
        if let cursor = cursor {
            operation = CKQueryOperation(cursor: cursor)
        } else if let query = query {
            operation = CKQueryOperation(query: query)
        } else {
            completion(accumulated)
            return
        }

// 限制每页返回的记录数
        // 注意：默认最多返回 100 条，这里设为 50 做分页演示
        operation.resultsLimit = 50

// 每查到一条匹配记录就回调一次
        // 类比：收银台每扫到一件商品就"嘀"一声
        operation.recordMatchedBlock = { recordID, result in
            switch result {
            case .success(let record):
                accumulated.append(record)
            case .failure(let error):
                print("获取单条记录失败 \(recordID): \(error)")
            }
        }

// 查询结束回调，根据是否返回 cursor 决定是否继续翻页
        operation.queryResultBlock = { [weak self] result in
            guard let self = self else { return }
            switch result {
            case .success(let nextCursor):
                if let nextCursor = nextCursor {
                    // 还有更多数据，用新的 cursor 继续查下一页
                    print("已获取 \(accumulated.count) 条，继续翻页...")
                    self.fetchPage(
                        query: nil,
                        cursor: nextCursor,
                        accumulated: &accumulated,
                        completion: completion
                    )
                } else {
                    // 没有更多数据了，返回全部结果
                    print("查询完成，共 \(accumulated.count) 条")
                    completion(accumulated)
                }
            case .failure(let error):
                print("查询失败: \(error)")
                completion(accumulated)
            }
        }

// 把 operation 提交给数据库执行
        privateDB.add(operation)
    }
}

// 注意： cursor（游标）是 CloudKit 分页查询的核心机制。它本质上是一个不透明的标记，记录了"上次查到哪里"。你不需要理解它的内部结构，只要把它原样传给下一次 CKQueryOperation(cursor:) 即可。cursor 有有效期，超时后使用会报错，所以分页查询应该在合理时间内连续进行。
6.3 查询限制
使用查询时必须清楚 CloudKit 的几条硬性限制，否则容易写出"本地测试没问题、上线后卡顿"的代码。
第一，每次查询最多返回 100 条记录。即使你不设置 resultsLimit，CloudKit 也会在 100 条处截断，通过 cursor 告诉你"还有更多"。所以任何"获取全部数据"的需求，都必须实现 cursor 翻页逻辑，不能假设一次查询就能拿全。
第二，Public Database 查询速度较慢。实测在 Public Database 上查询约 1000 条记录，耗时可能达到 10 秒级别。这是因为 Public Database 承载全量用户的数据读取，资源是共享的。如果你的 app 有大量公共数据需要频繁查询，应考虑本地缓存策略：首次全量拉取后缓存到本地（如 SwiftData），后续只查询增量更新。
第三，按需加载是推荐策略。不要在 app 启动时就拉取所有数据，而应该结合 UI 分页：列表先展示第一页，用户滚动到底部时再加载下一页。对于详情数据，先展示列表（轻量字段），用户点开某条时再按需读取完整内容。这样既能控制流量，又能给用户即时的响应感。
第四，查询的字段必须可索引。在 CloudKit Dashboard 的 RecordType 设置里，需要把要用于谓词筛选和排序的字段勾选为 indexable。如果没勾选，查询时会直接报错。

完整实战示例：简单的 iCloud 笔记应用
本节把前面所有知识点串联起来，构建一个完整可运行的 iCloud 笔记应用。它包含三部分：一个把笔记模型与 CloudKit 记录互转的 Model 层；一个封装了全部 CRUD 和查询操作的 Manager 层；一个展示笔记列表并支持新建、删除的 SwiftUI 界面。整个示例基于 Swift 5.9+ / iOS 17+，async/await 风格，包含详细注释。
7.1 Model 层：Note 模型与 CKRecord 互转
直接在业务代码里操作 CKRecord 会让数据访问逻辑和 CloudKit 强耦合。更好的做法是定义一个纯 Swift 模型，并提供与 CKRecord 互相转换的方法。这样上层只认识 Swift 模型，CloudKit 的细节被隔离在转换方法里。
import CloudKit
import Foundation

/// 笔记数据模型
/// 类比：一张填写好的笔记卡片在 Swift 里的投影
struct Note: Identifiable {
    let id: String          // 对应 CKRecord 的 recordName
    var title: String
    var content: String
    var createdAt: Date
    var modifiedAt: Date

/// 由 CKRecord 构造 Note 模型
    init(record: CKRecord) {
        // 注意：读取字段时用 as? 安全转换，转换失败给默认值
        self.id = record.recordID.recordName
        self.title = record["title"] as? String ?? "（无标题）"
        self.content = record["content"] as? String ?? ""
        self.createdAt = record["createdAt"] as? Date ?? Date()
        self.modifiedAt = record["modifiedAt"] as? Date ?? Date()
    }

/// 新建笔记时的便利构造器
    init(title: String, content: String) {
        self.id = UUID().uuidString
        self.title = title
        self.content = content
        self.createdAt = Date()
        self.modifiedAt = Date()
    }
}

extension Note {
    /// RecordType 常量，统一管理避免拼写错误
    // 注意：建议把 RecordType 和字段名集中定义为常量，防止散落在各处的硬编码字符串出错
    static let recordType = "Note"

static let fieldTitle = "title"
    static let fieldContent = "content"
    static let fieldCreatedAt = "createdAt"
    static let fieldModifiedAt = "modifiedAt"

/// 把 Note 模型转换成 CKRecord，用于保存到 CloudKit
    /// 如果传入已存在的 record，则在其上更新字段（用于修改场景）
    func toRecord(existing: CKRecord? = nil) -> CKRecord {
        let record = existing ?? CKRecord(
            recordType: Note.recordType,
            recordID: CKRecord.ID(recordName: id)
        )
        // 注意：设置字段值必须用 as CKRecordValue 转换
        record[Note.fieldTitle] = title as CKRecordValue
        record[Note.fieldContent] = content as CKRecordValue
        record[Note.fieldCreatedAt] = createdAt as CKRecordValue
        record[Note.fieldModifiedAt] = modifiedAt as CKRecordValue
        return record
    }
}

7.2 Manager 层：CloudKit 操作封装
把所有 CloudKit 调用集中在一个 Manager 类里，对外暴露纯 Swift 模型的方法，上层完全不接触 CKRecord。这个 Manager 包含了前面讲过的创建、读取、更新、删除和查询全部操作。
import CloudKit
import Foundation

/// 笔记的 CloudKit 数据管理器
/// 类比：一个负责和快递公司打交道的总管，上层只管下指令
final class NoteManager {
    // 单例，简化示例中的访问
    static let shared = NoteManager()

private let container: CKContainer
    private let database: CKDatabase

private init() {
        container = CKContainer.default()
        // 所有笔记都存在私有数据库
        // 类比：所有笔记卡片都放在用户的个人储物间
        database = container.privateCloudDatabase
    }

// MARK: - 创建

/// 新建一条笔记并保存到 iCloud
    func createNote(title: String, content: String) async throws -> Note {
        var note = Note(title: title, content: content)
        let record = note.toRecord()

// 注意：save 在 recordID 已存在时执行更新，不存在时执行新增
        let saved = try await database.save(record)
        // 用服务器返回的记录重新构造模型，确保元信息一致
        note = Note(record: saved)
        return note
    }

// MARK: - 读取单条

/// 根据记录 ID 读取单条笔记
    func fetchNote(id: String) async throws -> Note {
        let recordID = CKRecord.ID(recordName: id)
        // async 版本的 fetch
        let record = try await database.record(for: recordID)
        return Note(record: record)
    }

// MARK: - 更新

/// 更新一条已有笔记
    func updateNote(_ note: Note) async throws -> Note {
        // 先取出服务器上最新的记录，再在其基础上更新字段
        // 注意：直接用本地构造的 record 去 save 可能覆盖其他设备的并发修改
        // 这里先 fetch 再改，可降低 serverRecordChanged 冲突概率
        let recordID = CKRecord.ID(recordName: note.id)
        let existing = try await database.record(for: recordID)
        var updatedNote = note
        updatedNote.modifiedAt = Date()
        let record = updatedNote.toRecord(existing: existing)
        let saved = try await database.save(record)
        return Note(record: saved)
    }

// MARK: - 删除

/// 删除一条笔记
    func deleteNote(id: String) async throws {
        let recordID = CKRecord.ID(recordName: id)
        _ = try await database.deleteRecord(withID: recordID)
    }

// MARK: - 查询全部

/// 查询用户所有笔记，按修改时间倒序
    /// 内部实现了 cursor 翻页，确保拿到全部记录
    func fetchAllNotes() async throws -> [Note] {
        var notes: [Note] = []
        var cursor: CKQueryOperation.Cursor?

// 恒真谓词，查出所有 Note
        let query = CKQuery(
            recordType: Note.recordType,
            predicate: NSPredicate(value: true)
        )
        query.sortDescriptors = [
            NSSortDescriptor(key: Note.fieldModifiedAt, ascending: false)
        ]

// 循环翻页，直到 cursor 为 nil
        repeat {
            // 注意：首次用 query，后续用 cursor，二者只能传一个
            let (results, nextCursor): (
                [(CKRecord.ID, Result<CKRecord, Error>)],
                CKQueryOperation.Cursor?
            )
            if let cursor = cursor {
                results = try await fetchPage(cursor: cursor).matchResults
                nextCursor = try await fetchPage(cursor: cursor).queryCursor
            } else {
                // 首次查询用 records(matching:) 便捷方法
                let page = try await database.records(matching: query, resultsLimit: 100)
                results = page.matchResults
                nextCursor = page.queryCursor
            }
            cursor = nextCursor

// 把本页结果转成 Note 模型
            notes.append(contentsOf: results.compactMap { _, result in
                try? result.get()
            }.map { Note(record: $0) })
        } while cursor != nil

return notes
    }

/// 用 cursor 取下一页（演示 operation 写法）
    private func fetchPage(
        cursor: CKQueryOperation.Cursor
    ) async throws -> (matchResults: [(CKRecord.ID, Result<CKRecord, Error>)],
                        queryCursor: CKQueryOperation.Cursor?) {
        let operation = CKQueryOperation(cursor: cursor)
        operation.resultsLimit = 100

return try await withCheckedThrowingContinuation { continuation in
            var matchResults: [(CKRecord.ID, Result<CKRecord, Error>)] = []

operation.recordMatchedBlock = { recordID, result in
                matchResults.append((recordID, result))
            }

operation.queryResultBlock = { result in
                switch result {
                case .success(let cursor):
                    continuation.resume(
                        returning: (matchResults, cursor)
                    )
                case .failure(let error):
                    continuation.resume(throwing: error)
                }
            }

database.add(operation)
        }
    }

// MARK: - 条件查询

/// 按关键词搜索标题包含指定文本的笔记
    func searchNotes(keyword: String) async throws -> [Note] {
        // 注意：CONTAINS 做子串匹配，区分大小写
        let predicate = NSPredicate(
            format: "\(Note.fieldTitle) CONTAINS %@", keyword
        )
        let query = CKQuery(recordType: Note.recordType, predicate: predicate)
        query.sortDescriptors = [
            NSSortDescriptor(key: Note.fieldCreatedAt, ascending: false)
        ]

let (results, _) = try await database.records(matching: query, resultsLimit: 100)
        return results.compactMap { _, result in
            try? result.get()
        }.map { Note(record: $0) }
    }
}

// 注意： 上面 fetchAllNotes 里为了演示 cursor 翻页，混用了便捷 async 方法和 operation 写法，且对同一页做了两次请求，仅作教学演示。实际项目中应统一用一种方式，或直接循环调用 database.records(matching:resultsLimit:) 并把返回的 queryCursor 传给下一次调用即可，无需自己包一层 operation。
7.3 View 层：SwiftUI 笔记界面
最后用一个 SwiftUI 视图把功能串起来：列表展示笔记，支持新建和删除。这个视图直接调用 NoteManager，完全不感知 CloudKit 的存在，体现了分层带来的好处。
import SwiftUI

struct NoteListView: View {
    // 视图状态：笔记列表、加载状态、新建输入
    @State private var notes: [Note] = []
    @State private var isLoading = false
    @State private var errorMessage: String?

// 新建笔记的输入框状态
    @State private var newTitle = ""
    @State private var newContent = ""

private let manager = NoteManager.shared

var body: some View {
        NavigationStack {
            List {
                // 新建笔记的输入区
                // 类比：一张随时可以填写的空白卡片
                Section("新建笔记") {
                    TextField("标题", text: $newTitle)
                    TextField("内容", text: $newContent, axis: .vertical)
                        .lineLimit(2...5)
                    Button("保存到 iCloud") {
                        Task { await createNote() }
                    }
                    .disabled(newTitle.isEmpty)
                }

// 笔记列表
                Section("我的笔记（\(notes.count)）") {
                    if isLoading {
                        ProgressView("正在同步...")
                    }
                    ForEach(notes) { note in
                        VStack(alignment: .leading, spacing: 4) {
                            Text(note.title)
                                .font(.headline)
                            Text(note.content)
                                .font(.caption)
                                .foregroundStyle(.secondary)
                                .lineLimit(2)
                        }
                        .swipeActions {
                            // 左滑删除
                            Button(role: .destructive) {
                                Task { await deleteNote(note) }
                            } label: {
                                Label("删除", systemImage: "trash")
                            }
                        }
                    }
                }
            }
            .navigationTitle("iCloud 笔记")
            // 视图出现时加载笔记列表
            .task {
                await loadNotes()
            }
        }
    }

// MARK: - 操作方法

private func loadNotes() async {
        isLoading = true
        defer { isLoading = false }
        do {
            notes = try await manager.fetchAllNotes()
        } catch {
            errorMessage = "加载失败: \(error.localizedDescription)"
        }
    }

private func createNote() async {
        do {
            let note = try await manager.createNote(
                title: newTitle,
                content: newContent
            )
            // 注意：在主线程更新 UI 状态
            await MainActor.run {
                notes.insert(note, at: 0)
                newTitle = ""
                newContent = ""
            }
        } catch {
            errorMessage = "保存失败: \(error.localizedDescription)"
        }
    }

private func deleteNote(_ note: Note) async {
        do {
            try await manager.deleteNote(id: note.id)
            await MainActor.run {
                notes.removeAll { $0.id == note.id }
            }
        } catch {
            errorMessage = "删除失败: \(error.localizedDescription)"
        }
    }
}

#Preview {
    NoteListView()
}

7.4 运行前检查清单
在运行这个示例之前，请确认以下几点，否则会出现"代码对却跑不起来"的情况：
在 Xcode 的 Signing & Capabilities 里勾选了 iCloud 的 CloudKit，并创建了 Container。
Container ID 与 CKContainer.default() 期望的一致（默认会用 entitlements 里配置的第一个 Container）。
在模拟器或真机上登录了同一个 iCloud 账号（设置 → Apple 账户 → iCloud）。
在 CloudKit Dashboard 的 Development 环境里，运行一次 app 后会自动创建 Note 这个 RecordType，检查 title、content、createdAt、modifiedAt 字段是否存在，以及用于查询排序的字段是否勾选了 indexable。
运行后如果保存失败，重点查看控制台输出的错误码，常见的是 notAuthenticated（未登录 iCloud）或 permissionFailure（权限配置问题）。

本篇小结
本篇我们从"CloudKit 是搬数据的快递服务"这一定位出发，建立了 Container → Database → RecordZone → Record → Field 的完整数据模型认知，完成了 Xcode 环境配置，掌握了创建、读取、修改、删除四类基础操作，学习了基于 NSPredicate 的条件查询和基于 CKQueryOperation 的分页查询，最后用一个完整的 iCloud 笔记应用把所有知识点串联落地。
需要牢记的几条核心要点：CloudKit 是客户端驱动的数据搬运服务而非本地数据库；Private Database 占用户自己的 iCloud 空间；字段赋值要用 as CKRecordValue 转换、读取要用 as? 安全转换；修改和新增都用 save，CloudKit 靠 recordID 区分；每次查询最多 100 条，需要用 cursor 翻页；NSPredicate 只支持一个子集，且字段必须可索引。
掌握了本篇内容后，你已经具备了用 CloudKit 实现基础 iCloud 同步的能力。下一篇中级篇将深入三种数据库的协作、订阅与推送通知、数据共享（CKShare），以及 SwiftData 与 CloudKit 的原生集成。

CloudKit入门篇：CloudKit 基础

添加新评论 取消回复

添加新评论取消回复