修复上架后 CloudKit 同步失效：生产环境 Schema 部署指南

核心摘要：CloudKit 将数据环境严格隔离为“开发环境”和“生产环境”。App Store 版本默认连接生产环境，如果你的 CloudKit Schema（数据库结构）没有手动部署到生产环境，同步功能将彻底失效。

很多开发者（尤其是 SwiftData/Core Data 新手）常遇到一个经典崩溃场景：App 在 Xcode 调试时云同步丝般顺滑，一旦发布到 TestFlight 或 App Store，用户数据却完全无法同步。这并非代码 Bug，而是 CloudKit 部署流程的问题。

根源：环境隔离机制

CloudKit 包含两个独立环境：

Development (开发环境)：仅供开发人员使用。在该环境下，CloudKit 支持 JIT (Just-In-Time) Schema，即当你写入新类型的数据时，服务器会自动创建对应的表结构。
Production (生产环境)：供真实用户使用。为了性能和数据安全，生产环境禁止自动创建或修改 Schema。

问题所在：当你的 App 上架后，它连接的是生产环境。如果生产环境没有对应的 Schema 定义，CloudKit 会拒绝数据的读写请求。

解决方案：部署 Schema

要修复此问题，你必须手动将开发环境的结构“复制”到生产环境。

1. 访问 CloudKit 仪表盘

2. 执行部署 (Deploy to Production)

在左侧菜单找到 Schema -> Deploy Schema Changes（或在 Record Types 页面右上角）。点击 Deploy 按钮，系统会将开发环境当前的数据库结构应用到生产环境。

CloudKit Deploy Schema

重要提示：每次修改了 Core Data 或 SwiftData 的数据模型（Model）并准备发布新版本前，都必须重复此步骤。

TestFlight 的特殊情况

默认情况下，TestFlight 构建的版本被视为“准生产版本”，因此它默认连接 Production 环境。

如果你希望在 TestFlight 中测试 Development 环境（例如测试新的 Schema 变更），需要修改项目的 Entitlements.plist 文件：

XML

<key>com.apple.developer.icloud-container-environment</key>
<array>
    <!-- 默认是 Production，改为 Development 即可连接开发库 -->
    <string>Development</string>
</array>

注意：提交给 App Store 审核的正式包，该值必须自动变回 Production（Xcode Archive 时通常会自动处理，但建议检查）。

最佳实践清单

发版前检查：在提交审核前，务必去 CloudKit Console 确认是否有未部署的 Schema 变更。
重置开发环境：如果开发环境数据过脏，可在控制台使用 Reset Environment 重置（注意：这会清空开发库的所有数据和结构，需重新运行 App 生成结构）。
SwiftData 用户：SwiftData 的底层机制与 Core Data 一致，同样遵循此部署规则。