修复 macOS SwiftData/Core Data 同步失效：手动添加 CloudKit.framework

macOS 应用在使用 Core Data 或 SwiftData 进行 iCloud 同步时，必须在项目的 “Frameworks, Libraries, and Embedded Content” 中显式添加 CloudKit.framework。否则，虽然编译能通过，但发布版本的同步功能会静默失败。

问题现象

开发者在将 iOS 应用移植到 macOS（无论是原生还是 Mac Catalyst）时，常遇到以下诡异情况：

1. 调试环境正常：在 Xcode 中直接运行（Debug 模式），数据可以在 iPhone 和 Mac 之间秒级同步。
2. 生产环境失效：一旦打包上传到 TestFlight，或者导出为 Release 版本，macOS 端的数据就“断连”了，既不上传也不下载。
3. 无报错信息：应用不会崩溃，Console 中甚至可能看不到明显的 CloudKit 错误日志，或者提示容器不可用。
4. 权限看似正常：Signing & Capabilities 中的 iCloud 和 Background Modes 配置均正确。

根本原因

在 iOS 项目中，Xcode 的构建系统通常会自动隐式链接 CloudKit 框架。但在 macOS 项目（尤其是某些模板或从 iOS 迁移的项目）中，这种自动链接可能不会发生。

当缺少 CloudKit.framework 链接时：

• Debug 模式：由于调试器和动态链接器的宽松行为，可能会意外加载该框架，导致“假通”。
• Release 模式：系统严格检查依赖，缺少框架导致 CloudKit 服务无法初始化，从而切断了 NSPersistentCloudKitContainer 或 SwiftData ModelContainer 的同步能力。

解决方案

修复方法非常简单，只需手动强制链接该框架：

1. 添加框架依赖

1. 在 Xcode 中点击项目根节点（Project Navigator）。
2. 选择 macOS 应用的 Target。
3. 进入 Build Phases 选项卡（或者 General 选项卡）。
4. 找到 Link Binary With Libraries (或 Frameworks, Libraries, and Embedded Content)。
5. 点击 + 号，搜索并添加 CloudKit.framework。

2. 重新构建验证

Clean Build Folder (Cmd + Shift + K)，然后重新归档（Archive）并上传到 TestFlight。此时同步功能应恢复正常。

延伸阅读

• Core Data with CloudKit：同步本地数据库到 iCloud