SwiftData 用 @Model 定义模型、入口挂 .modelContainer、@Query 读数据、modelContext 增删,改模型时用 VersionedSchema 和 SchemaMigrationPlan 迁移。SwiftData 要求 iOS 17 及以上,本文用待办 App 实战。
SwiftData 怎么用?用 @Model 定义模型,在 App 入口挂上 .modelContainer,界面用 @Query 读数据、用 modelContext 增删,改模型时用 VersionedSchema 和 SchemaMigrationPlan 迁移旧数据。SwiftData 要求 iOS 17 及以上,要支持 iOS 16 及以下的 App 继续用 Codable 文件或 Core Data。
本文把[第一个 SwiftUI App]里用 JSON 文件存数据的待办清单 MyTodo 改成 SwiftData 本地存储。全部代码在部署目标 iOS 17、Swift 5 和 Swift 6 语言模式下编译通过。做完以后你会得到一个能搜索、能过滤、能编辑、带分组关系的待办 App,旧版本存在 todos.json 里的数据会在第一次启动时自动导入,这是VSCode 插件
用 SwiftData 之前要准备什么?
- 工程。用 129 篇做好的 MyTodo,或者新建一个。新建时在命令面板运行
KXBuild: 新建项目,模板选「iOS 应用(SwiftUI)」,或在 PowerShell 执行下面的命令。
kxbuild project create -t app_swiftui -n MyTodo -b com.yourname.mytodo -o D:\projects
-
部署目标改成 iOS 17。内置模板的部署目标是 iOS 15,而 SwiftData 从 iOS 17 起才有。在 KXBuild 视图中右键 target 选「KXBuild: 编辑目标设置」,在 General 页把 iOS Deployment Target 改成
17.0,按 Ctrl+S 保存,见[工程设置]。不改的话编译会报
'Model()' is only available in iOS 17 or newer。 -
证书和手机。真机运行需要的证书目录和设备连接,按 129 篇的「装到 iPhone 上运行」做好。
和 129 篇一样,代码都写在 ContentView.swift 和 MyTodoApp.swift 两个文件里,省去往工程里添加新文件的步骤。
第 1 步:定义模型和关系
把 ContentView.swift 的内容整个换掉,先写下面两个模型。129 篇里的 TodoStore 类不再需要,原来的 TodoItem 结构体在第五步改个名字留着导入旧数据用。
import SwiftUI
import SwiftData
@Model
final class TodoItem {
@Attribute(.unique) var id: UUID
var title: String
var done: Bool
var createdAt: Date
var group: TodoGroup?
init(id: UUID = UUID(), title: String, done: Bool = false, createdAt: Date = .now) {
self.id = id
self.title = title
self.done = done
self.createdAt = createdAt
}
}
@Model
final class TodoGroup {
var name: String
@Relationship(deleteRule: .cascade, inverse: \TodoItem.group)
var items: [TodoItem] = []
init(name: String) {
self.name = name
}
}
@Model把一个 class 变成可持久化的模型。存储属性都会存进数据库,类型本身也自动可被 SwiftUI 观察,属性一改界面就刷新。模型必须是 class,不能是 struct。@Attribute(.unique)让id唯一。插入一条id已存在的数据时,SwiftData 会更新原来那条而不是新增一条,后面导入旧数据时靠它防止重复。- 关系。
TodoItem.group是多对一,TodoGroup.items是一对多,inverse指明两边是同一个关系,改一边另一边自动跟着变。 - 不想存的属性加
@Transient,并且给默认值,例如只在界面上用的临时计数。
deleteRule 决定删掉一个分组时,组里的待办怎么处理。
| 删除规则 | 删除 TodoGroup 时 | 适合 |
|---|---|---|
.nullify(默认) | 组里每条待办的 group 变成 nil,待办保留 | 分组只是标签,删组不该丢数据 |
.cascade | 组里的待办一起删除 | 子数据离开父对象就没有意义,例如订单和订单行 |
.deny | 组里还有待办时不允许删除 | 必须先清空才能删的容器 |
.noAction | 不处理相关的待办 | 你自己维护引用,一般不用 |
这里用 .cascade,删一个分组连同里面的待办一起删。想保留待办就去掉 deleteRule: 参数,用默认的 .nullify。
第 2 步:挂上 modelContainer
ModelContainer 负责打开数据库文件,.modelContainer 修饰符把它放进 SwiftUI 环境,下面所有视图都能拿到。把 MyTodoApp.swift 换成下面的内容。
import SwiftUI
import SwiftData
@main
struct MyTodoApp: App {
var body: some Scene {
WindowGroup {
ContentView()
}
.modelContainer(for: TodoItem.self)
}
}
只写 TodoItem.self 就够了,SwiftData 会顺着关系把 TodoGroup 也加进来。从环境里拿到的 modelContext 会定期检查有没有未保存的改动并自动保存,所以下面的增删改代码里不需要每次调用 save()。Apple 的说明见 [Preserving your app's model data across launches]。
第 3 步:列表、增删改
在 ContentView.swift 模型的下面加上界面代码。顶部输入框添加待办,点圆圈切换完成,点标题进入编辑页,左滑删除。
struct ContentView: View {
@Environment(\.modelContext) private var context
@State private var newTitle = ""
@State private var searchText = ""
@State private var hideDone = false
var body: some View {
NavigationStack {
List {
Section {
HStack {
TextField("新的待办", text: $newTitle)
.onSubmit(add)
Button("添加", action: add)
.disabled(newTitle.trimmingCharacters(in: .whitespaces).isEmpty)
}
Toggle("隐藏已完成", isOn: $hideDone)
}
TodoListSection(searchText: searchText, hideDone: hideDone)
}
.searchable(text: $searchText, prompt: "搜索待办")
.navigationTitle("待办")
.navigationDestination(for: TodoItem.self) { item in
TodoDetailView(item: item)
}
.toolbar { EditButton() }
.task {
LegacyImporter.importIfNeeded(into: context)
if let url = context.container.configurations.first?.url {
print("SwiftData 存储位置 \(url.path)")
}
}
}
}
private func add() {
let title = newTitle.trimmingCharacters(in: .whitespaces)
guard !title.isEmpty else { return }
context.insert(TodoItem(title: title))
newTitle = ""
}
}
struct TodoListSection: View {
@Environment(\.modelContext) private var context
@Query private var items: [TodoItem]
init(searchText: String, hideDone: Bool) {
let predicate = #Predicate<TodoItem> { item in
(searchText.isEmpty || item.title.localizedStandardContains(searchText))
&& (!hideDone || !item.done)
}
_items = Query(filter: predicate, sort: \TodoItem.createdAt)
}
var body: some View {
Section {
ForEach(items) { item in
HStack {
Button {
item.done.toggle()
} label: {
Image(systemName: item.done ? "checkmark.circle.fill" : "circle")
.foregroundStyle(item.done ? .green : .secondary)
}
.buttonStyle(.plain)
NavigationLink(value: item) {
Text(item.title)
.strikethrough(item.done)
}
}
}
.onDelete { offsets in
for index in offsets {
context.delete(items[index])
}
}
} footer: {
Text("共 \(items.count) 条")
}
}
}
struct TodoDetailView: View {
@Bindable var item: TodoItem
var body: some View {
Form {
TextField("标题", text: $item.title)
Toggle("已完成", isOn: $item.done)
LabeledContent("创建时间", value: item.createdAt.formatted(date: .abbreviated, time: .shortened))
if let group = item.group {
LabeledContent("分组", value: group.name)
}
}
.navigationTitle("编辑待办")
}
}
.task 里调用的 LegacyImporter 在第五步补上,现在先别编译。
四种操作分别对应下面的写法。
| 操作 | 写法 | 说明 |
|---|---|---|
| 增 | context.insert(TodoItem(title: title)) | 插入后 @Query 立即包含这一条,界面自动刷新 |
| 删 | context.delete(items[index]) | 有 .cascade 关系的会连带删除相关对象 |
| 改 | item.done.toggle()、item.title = "…" | 直接改属性,不需要 update 语句 |
| 查 | @Query、context.fetch(_:) | 视图里用 @Query,视图以外用 FetchDescriptor |
编辑页的 @Bindable 让你能对模型的属性写 $item.title 这样的绑定,TextField 里每输入一个字就改一次模型。@Query 只能在 SwiftUI 视图里用,放在普通的类里不会工作。
第 4 步:用 #Predicate 排序和过滤
@Query 写在属性上时条件是固定的。条件要跟着搜索框、开关变化,就像上面的 TodoListSection 一样,把条件作为初始化参数传进子视图,在 init 里给 _items 赋一个新的 Query。父视图的 searchText 一变,子视图重新创建,查询也跟着换。
#Predicate 里写的是 Swift 表达式,SwiftData 把它翻译成数据库查询。
- 能用的:比较运算、
&&、||、!,字符串的contains、localizedStandardContains(忽略大小写和变音符号),可选值和关系的比较,以及从外面捕获的常量,例如这里的searchText和hideDone。 - 不能用的:任意方法和计算属性。例如写
$0.title.uppercased() == s,编译直接报The uppercased() function is not supported in this predicate。需要按大小写无关搜索就用localizedStandardContains,需要复杂计算的条件可以先存成一个单独的属性。
排序传给 sort:,可以是一个 key path,也可以是 SortDescriptor 数组。在视图以外查数据,例如统计或导出,用 FetchDescriptor。
@MainActor
func todayUnfinished(context: ModelContext) throws -> [TodoItem] {
let todayStart = Calendar.current.startOfDay(for: .now)
let descriptor = FetchDescriptor<TodoItem>(
predicate: #Predicate { !$0.done && $0.createdAt >= todayStart },
sortBy: [SortDescriptor(\.createdAt, order: .reverse)]
)
return try context.fetch(descriptor)
}
只要数量时用 try context.fetchCount(descriptor),不必把对象都取出来。todayStart 要先算好放进常量,#Predicate 里不能调用 Calendar 的方法。
用关系查询和赋值
给待办设置分组,直接给 group 赋值,TodoGroup.items 会自动多出这一条。
@MainActor
func addWorkItem(context: ModelContext) {
let work = TodoGroup(name: "工作")
context.insert(work)
let item = TodoItem(title: "写周报")
item.group = work
context.insert(item)
print(work.items.count)
}
这时调用 context.delete(work),因为删除规则是 .cascade,「写周报」也会一起删掉。
第 5 步:从 JSON 文件导入旧数据
129 篇的 MyTodo 把待办存在 Documents 目录的 todos.json 里。已经装过旧版本的手机升级后,要把这些数据一次性搬进 SwiftData。在 ContentView.swift 里加上下面的代码,LegacyTodoItem 就是原来的 TodoItem 结构体改了名字,字段和 JSON 的键保持一致。
struct LegacyTodoItem: Codable {
var id: UUID
var title: String
var done: Bool
}
enum LegacyImporter {
@MainActor
static func importIfNeeded(into context: ModelContext) {
let fileURL = URL.documentsDirectory.appending(path: "todos.json")
guard FileManager.default.fileExists(atPath: fileURL.path) else { return }
do {
let data = try Data(contentsOf: fileURL)
let oldItems = try JSONDecoder().decode([LegacyTodoItem].self, from: data)
let start = Date.now.addingTimeInterval(-Double(oldItems.count))
for (index, old) in oldItems.enumerated() {
context.insert(TodoItem(
id: old.id,
title: old.title,
done: old.done,
createdAt: start.addingTimeInterval(Double(index))
))
}
try context.save()
let doneURL = URL.documentsDirectory.appending(path: "todos.imported.json")
try? FileManager.default.removeItem(at: doneURL)
try FileManager.default.moveItem(at: fileURL, to: doneURL)
print("已从 todos.json 导入 \(oldItems.count) 条")
} catch {
print("导入失败 \(error)")
}
}
}
这段代码保证只导入一次,也不会重复。
- 只跑一次。导入成功后把
todos.json改名为todos.imported.json,下次启动找不到原文件就直接返回。保留改名后的文件,万一导入有问题还能找回原始数据,确认没问题后的下一个版本再删掉。 - 不会重复。沿用旧数据的
id,加上@Attribute(.unique),即使导入中途被杀掉、下次重新导入,同一条也只会更新不会新增。 - 保持顺序。旧 JSON 没有创建时间,按数组顺序每条相差一秒生成
createdAt,列表按createdAt排序后和原来一样。 - 立即保存。导入后显式调用
save(),确认写进数据库后才改名原文件,不依赖自动保存的时机。
数据量很大时把导入挪到后台执行,见下一节。
SwiftData 怎么在后台线程批量写入?
context.container.mainContext 和环境里的 modelContext 都属于主线程。批量导入、同步服务器数据这种耗时的写入,用 @ModelActor 声明一个 actor,它自带一个只在这个 actor 里使用的 modelContext。
@ModelActor
actor TodoBackgroundImporter {
func importTitles(_ titles: [String]) throws -> Int {
for title in titles {
modelContext.insert(TodoItem(title: title))
}
try modelContext.save()
return titles.count
}
}
@MainActor
func runBackgroundImport(container: ModelContainer) async {
let importer = TodoBackgroundImporter(modelContainer: container)
do {
let count = try await importer.importTitles(["示例 1", "示例 2"])
print("后台导入 \(count) 条")
} catch {
print("后台导入失败 \(error)")
}
}
在视图里用 await runBackgroundImport(container: context.container) 调用。后台 context 不会自动保存,写完要调用 save(),否则数据不会写进数据库。
要在后台修改界面上的某一条,把它的 persistentModelID 传过去,在 actor 里用 modelContext.model(for:) 取回来再改,不要把 ModelContext 本身传到别的线程。Apple 的说明见 [ModelActor]。
怎么在 iPhone 上确认数据存下来了?
数据在重启和覆盖安装后还在
- 按 F5,KXBuild 构建、签名、安装并启动 App。添加几条待办,勾选一条,进编辑页改一个标题。
- 在手机上上滑把 App 从后台划掉,再点图标打开,刚才的改动都在。
- 改一行代码,例如把
navigationTitle("待办")改成navigationTitle("我的待办"),按 Shift+F5 停止调试再按 F5。这次是覆盖安装,数据仍然在。 - 装过 129 篇旧版本的手机,第一次运行时「输出 → KXBuild Console」里会打印
已从 todos.json 导入 N 条,列表里出现原来的待办。
数据只在卸载 App 时被删除。覆盖安装、升级版本都会保留同一个 Bundle ID 下的数据,所以模型改动必须考虑已有数据,见下一节的迁移。
查看数据库文件的位置
上面 .task 里打印了存储位置,运行后在「输出 → KXBuild Console」能看到类似下面的一行,具体路径以你手机上的输出为准。
SwiftData 存储位置 /private/var/mobile/Containers/Data/Application/<UUID>/Library/Application Support/default.store
路径里 Application/<UUID>/ 之后的部分就是 App 沙盒里的位置。用 kxdevice 列出沙盒的 Library 目录,确认文件确实写到了手机上。一般是一个 .store 文件,旁边可能还有同名的 -wal、-shm 文件。
kxdevice file --app com.yourname.mytodo tree /Library
这个命令只对你自己签名安装的 App 有效,用法见 [kxdevice 命令参考]。
用断点看数据
在 add() 的 context.insert(...) 这一行打断点,在手机上添加一条,停住后在调试控制台输入 po title 看要插入的标题,按 F10 单步越过这一行,再按 F5 继续,列表底部的「共 N 条」加一。切换「隐藏已完成」或在搜索框输入文字,底部的条数跟着变,说明过滤条件生效。断点和调试控制台的用法见[运行与调试]。
改了模型怎么做 SwiftData 迁移?
App 发布后再改模型,手机上已有的数据库还是旧结构。SwiftData 打开数据库时会比较新旧结构,能自动转换的直接转换,不能的就打开失败。
哪些改动能自动迁移
| 改动 | 迁移方式 | 做法 |
|---|---|---|
| 新增有默认值的属性 | 轻量迁移,自动完成 | var priority: Int = 0 |
| 新增可选属性 | 轻量迁移,自动完成 | var dueDate: Date? |
| 属性改名 | 轻量迁移,要标出旧名 | @Attribute(originalName: "done") var isCompleted: Bool |
| 修改关系的删除规则 | 轻量迁移 | 改 deleteRule: |
| 给已有数据加唯一约束 | 不能轻量迁移 | 用自定义迁移阶段先去重 |
| 新增非可选、无默认值的属性 | 旧数据没有值,迁移失败 | 加默认值或改成可选 |
| 改属性类型、拆分合并字段 | 需要自定义迁移 | 用 .custom 阶段转换数据 |
属性改名时只改名字不写 originalName,SwiftData 会当成删了一个属性、加了一个新属性,旧值就丢了。改名、删除规则可以轻量迁移,加唯一约束需要自定义阶段,这几条出自 Apple 的 WWDC23 讲座 [Model your schema with SwiftData]。
用 VersionedSchema 管理版本
只做轻量迁移时可以不写迁移代码。从第一次正式发版开始,建议把每个发布过的模型版本都存成一个 VersionedSchema,以后需要自定义迁移时版本链是完整的。
下面把已经发布的模型存为 V1,V2 新增优先级和截止日期两个字段。把 ContentView.swift 里第一步写的两个 @Model 类删掉,换成下面的代码,其他代码不用改。
enum TodoSchemaV1: VersionedSchema {
static let versionIdentifier = Schema.Version(1, 0, 0)
static var models: [any PersistentModel.Type] {
[TodoItem.self, TodoGroup.self]
}
@Model
final class TodoItem {
@Attribute(.unique) var id: UUID
var title: String
var done: Bool
var createdAt: Date
var group: TodoGroup?
init(id: UUID = UUID(), title: String, done: Bool = false, createdAt: Date = .now) {
self.id = id
self.title = title
self.done = done
self.createdAt = createdAt
}
}
@Model
final class TodoGroup {
var name: String
@Relationship(deleteRule: .cascade, inverse: \TodoItem.group)
var items: [TodoItem] = []
init(name: String) {
self.name = name
}
}
}
enum TodoSchemaV2: VersionedSchema {
static let versionIdentifier = Schema.Version(2, 0, 0)
static var models: [any PersistentModel.Type] {
[TodoItem.self, TodoGroup.self]
}
@Model
final class TodoItem {
@Attribute(.unique) var id: UUID
var title: String
var done: Bool
var createdAt: Date
var priority: Int = 0
var dueDate: Date?
var group: TodoGroup?
init(id: UUID = UUID(), title: String, done: Bool = false, createdAt: Date = .now) {
self.id = id
self.title = title
self.done = done
self.createdAt = createdAt
}
}
@Model
final class TodoGroup {
var name: String
@Relationship(deleteRule: .cascade, inverse: \TodoItem.group)
var items: [TodoItem] = []
init(name: String) {
self.name = name
}
}
}
typealias TodoItem = TodoSchemaV2.TodoItem
typealias TodoGroup = TodoSchemaV2.TodoGroup
enum TodoMigrationPlan: SchemaMigrationPlan {
static var schemas: [any VersionedSchema.Type] {
[TodoSchemaV1.self, TodoSchemaV2.self]
}
static var stages: [MigrationStage] {
[migrateV1toV2]
}
static var migrateV1toV2: MigrationStage {
.lightweight(fromVersion: TodoSchemaV1.self, toVersion: TodoSchemaV2.self)
}
}
- V1 必须和已发布的模型一字不差。属性、类型、关系、属性标注都要和用户手机上那一版完全一致,SwiftData 靠它认出旧数据库是哪个版本。
typealias指向最新版本。界面代码里的TodoItem自动指向 V2,原来的增删改查不用改。schemas按从旧到新排列,stages列出相邻两个版本之间怎么迁移。
然后把 MyTodoApp.swift 换成显式创建容器的写法,传入迁移计划。
import SwiftUI
import SwiftData
@main
struct MyTodoApp: App {
let container: ModelContainer
init() {
do {
container = try ModelContainer(
for: TodoItem.self, TodoGroup.self,
migrationPlan: TodoMigrationPlan.self
)
} catch {
fatalError("无法打开数据库:\(error)")
}
}
var body: some Scene {
WindowGroup {
ContentView()
}
.modelContainer(container)
}
}
fatalError 会把具体的迁移错误打印到「输出 → KXBuild Console」。正式版本可以换成显示一个错误页面并上报日志,不要静默删库重建。
自定义迁移阶段
迁移时需要按旧数据计算新字段,例如把所有未完成的待办设成优先级 1,就用 .custom。willMigrate 在结构变更前执行,拿到的是旧版本的数据,适合去重、清理;didMigrate 在变更后执行,拿到的是新版本的数据,适合填充新字段。把 TodoMigrationPlan 里的 migrateV1toV2 换成下面这个。
static var migrateV1toV2: MigrationStage {
.custom(
fromVersion: TodoSchemaV1.self,
toVersion: TodoSchemaV2.self,
willMigrate: nil,
didMigrate: { context in
let items = try context.fetch(FetchDescriptor<TodoSchemaV2.TodoItem>())
for item in items where !item.done {
item.priority = 1
}
try context.save()
}
)
}
在真机上测迁移
- 先用 V1 的代码按 F5 装到手机上,添加几条待办。
- 换成 V2 和迁移计划的代码,再按 F5 覆盖安装。这一步模拟的就是用户从旧版本升级。
- App 正常启动、旧待办都在,迁移就是成功的。启动即崩溃时看「输出 → KXBuild Console」里的错误,再对照下面的报错表。
开发阶段模型还没发布,随便改字段后启动失败的话,删掉手机上的 App 重装就能从空数据库开始,命令是 kxdevice apps uninstall com.yourname.mytodo。发布之后不能这样做,必须写迁移。
SwiftData 常见报错怎么解决?
| 现象或报错 | 原因 | 解决 |
|---|---|---|
编译报 'Model()' is only available in iOS 17 or newer | 部署目标低于 iOS 17 | 在「编辑目标设置」的 General 页把 iOS Deployment Target 改成 17.0 |
编译报 main actor-isolated property 'mainContext' cannot be accessed from outside of the actor | 在 Task.detached 或后台队列里用了 mainContext | 后台写入改用 @ModelActor,主线程的 context 只在主线程用 |
编译报 non-Sendable type 'ModelContext' ... cannot exit main actor-isolated context,Swift 5 模式下是警告 | 把 ModelContext 带到了另一个线程 | 每个 actor 用自己的 context,跨线程只传 persistentModelID |
编译报 The uppercased() function is not supported in this predicate | #Predicate 里调用了不支持的方法 | 改用 localizedStandardContains 这类支持的写法,或把计算结果存成属性 |
| 改了模型字段后启动即崩溃 | 新增了非可选、无默认值的属性,或改名、改类型时没有对应的迁移 | 新属性给默认值或改成可选,改名加 originalName,复杂改动写 .custom 阶段 |
加 @Attribute(.unique) 后旧数据打不开 | 唯一约束不是轻量迁移,旧数据里可能已有重复值 | 加一个新版本,在 .custom 的 willMigrate 里先去重 |
| 一插入数据或一显示列表就崩溃 | 没有挂 .modelContainer,或挂在了用到数据的视图之外 | 把 .modelContainer 挂在 WindowGroup 上 |
| 后台写入的数据重启后不见了 | 后台 context 没有调用 save() | 写完调用 try modelContext.save() |
| 每次启动旧数据都多一份 | 导入代码没有标记已完成,模型也没有唯一 id | 导入后改名原文件,并沿用旧数据的 id 加 @Attribute(.unique) |
@Query 的结果不随搜索框变化 | 条件写死在属性上 | 把条件作为参数传进子视图,在 init 里重建 Query |
崩溃时的完整调用栈和变量可以在调试视图里看,排查方法见 [Windows 上真机调试 iOS App]。并发相关报错的完整改法见 [Swift 6 严格并发常见报错]。
要支持 iOS 16 及以下怎么办?
SwiftData 的所有类型都要求 iOS 17,不能向下兼容,也没有可以单独打包的版本。最低版本低于 iOS 17 时按数据量选。
| 情况 | 建议 |
|---|---|
| 几十到几百条、结构简单 | 继续用 129 篇的 Codable + JSON 文件,ObservableObject 驱动界面 |
| 数据多、要按条件查询、有关系 | 用 Core Data,iOS 3 起就有,@FetchRequest 在 SwiftUI 里的用法和 @Query 类似 |
| 打算一两个版本后把最低版本升到 17 | 现在用 Codable 文件,升级时用第五步的导入代码一次性搬进 SwiftData |
不建议用 if #available(iOS 17, *) 在同一个 App 里同时维护 SwiftData 和另一套存储。两套代码要分别测试,升级系统的用户还要做跨存储迁移,复杂度远超收益。最低版本怎么定可以参考 [SwiftUI 还是 UIKit:2026 年新项目怎么选]。
常见问题
SwiftData 最低支持哪个 iOS 版本?
iOS 17。@Model、ModelContainer、@Query 都要求 iOS 17 及以上,部署目标更低时编译直接报错。#Unique、#Index 这类后来加的功能要求 iOS 18。
SwiftData 的数据库文件存在 App 的哪里?
默认存在 App 沙盒的 Library 目录下。最准确的办法是打印 context.container.configurations.first?.url,运行后在「输出 → KXBuild Console」查看,再用 kxdevice file --app <Bundle ID> tree /Library 确认文件在手机上。
改了 SwiftData 模型以后 App 启动就崩溃怎么办?
开发阶段直接卸载 App 重装,从空数据库开始。已经发布过的版本要给新属性加默认值或改成可选,改名用 @Attribute(originalName:),复杂改动用 VersionedSchema 和 SchemaMigrationPlan 写迁移,再用旧版本覆盖安装新版本测试。
SwiftData 要手动调用 save() 吗?
从环境拿到的 modelContext 和 mainContext 会自动保存,一般不用手动调用。自己用 @ModelActor 或 ModelContext(container) 创建的 context 写完要调用 save(),导入旧数据这种必须确认落盘的操作也建议显式保存。
SwiftData 和 Core Data 怎么选?
最低 iOS 17 的新项目用 SwiftData,模型和查询直接写在 Swift 代码里,和 SwiftUI 配合最省事。要支持 iOS 16 及以下,或者已经有成熟的 Core Data 模型,就继续用 Core Data。
更多教程可以查看官网:www.kxbuild.net/zh/tutorial…