核心摘要：CloudKit 数据库默认不为字段创建索引。若要在 CloudKit Console 中浏览数据列表，必须手动为 recordName 字段添加 Queryable 索引。
问题描述
很多开发者在集成 Core Data 或 SwiftData 的 CloudKit 同步功能后，会遇到一个令人困惑的现象：
应用在多台设备间同步完全正常，但在 Apple Developer 的 CloudKit Console（控制台）中查询 Records 时，却显示“No Records Found”或一片空白。
原因分析
这并非同步失败，而是 CloudKit 的索引机制导致的：
- 按需索引：与传统关系型数据库不同，CloudKit 为了性能，默认不会为字段建立索引。
- 查询限制：没有索引的字段无法被查询（Query）、搜索或排序。
- Core Data/SwiftData 的行为：这两个框架自动管理的 Schema（CD_前缀的表）在部署到 CloudKit 时，默认不包含任何可视化所需的索引配置。
因此，虽然数据真实存在于云端，但控制台因无法执行“查询所有数据”的指令而显示为空。
解决方案
要解决此问题，需在 CloudKit Dashboard 中手动添加索引。
1. 关键步骤：使记录可见
要让数据在列表中显示出来，必须至少让 CloudKit 能够“查询”到这些记录的主键。
- 进入 CloudKit Console -> Indexes。
- 选择对应的 Record Type（通常以
CD_开头）。 - 找到系统字段
recordName。 - 点击 Add Index，选择
QUERYABLE。 - 保存更改。
完成此步后，返回 Records 页面点击 Query，即可看到数据列表。
2. 进阶配置：搜索与排序
如果你希望在控制台中根据特定字段（如 name 或 timestamp）进行过滤或排序，需单独添加索引：
- Queryable：允许精确匹配查询。
- Sortable：允许按字段排序。
- Searchable：允许全文搜索（仅支持
String类型）。
注意：索引配置是分离的。如果你既想查询又想排序，需分别为同一个字段添加 QUERYABLE 和 SORTABLE 两条索引记录。
