为什么 CloudKit 控制台看不到 Core Data/SwiftData 的同步数据？

问题描述

很多开发者在集成 Core Data 或 SwiftData 的 CloudKit 同步功能后，会遇到一个令人困惑的现象： 应用在多台设备间同步完全正常，但在 Apple Developer 的 CloudKit Console（控制台）中查询 Records 时，却显示“No Records Found”或一片空白。

原因分析

这并非同步失败，而是 CloudKit 的索引机制导致的：

1. 按需索引：与传统关系型数据库不同，CloudKit 为了性能，默认不会为字段建立索引。
2. 查询限制：没有索引的字段无法被查询（Query）、搜索或排序。
3. Core Data/SwiftData 的行为：这两个框架自动管理的 Schema（CD_前缀的表）在部署到 CloudKit 时，默认不包含任何可视化所需的索引配置。

因此，虽然数据真实存在于云端，但控制台因无法执行“查询所有数据”的指令而显示为空。

解决方案

要解决此问题，需在 CloudKit Dashboard 中手动添加索引。

1. 关键步骤：使记录可见

要让数据在列表中显示出来，必须至少让 CloudKit 能够“查询”到这些记录的主键。

1. 进入 CloudKit Console -> Indexes。
2. 选择对应的 Record Type（通常以 CD_ 开头）。
3. 找到系统字段 recordName。
4. 点击 Add Index，选择 QUERYABLE。
5. 保存更改。

完成此步后，返回 Records 页面点击 Query，即可看到数据列表。

2. 进阶配置：搜索与排序

如果你希望在控制台中根据特定字段（如 name 或 timestamp）进行过滤或排序，需单独添加索引：

• Queryable：允许精确匹配查询。
• Sortable：允许按字段排序。
• Searchable：允许全文搜索（仅支持 String 类型）。

注意：索引配置是分离的。如果你既想查询又想排序，需分别为同一个字段添加 QUERYABLE 和 SORTABLE 两条索引记录。

延伸阅读

• Core Data with CloudKit（三）—— CloudKit 仪表台详解