在 .NET MAUI 中用 SQLite 做本地数据存储，核心就三件事：装对包、定好路径、写好访问逻辑。不复杂但容易忽略细节，比如少装一个依赖或路径写错，运行时直接报错。
必须安装的两个 NuGet 包
只装 sqlite-net-pcl 不够，它依赖底层 SQLite 实现，必须同步安装对应平台的绑定包：
sqlite-net-pcl（作者：praeclarum）—— 提供SQLiteAsyncConnection和模型映射能力 SQLitePCLRaw.bundle_green（不是 bundle_e_sqlite3 或其他变体）—— 为 Android/iOS/macOS/Windows 提供统一的原生 SQLite 支持
如果漏装
bundle_green，App 启动时大概率抛出
System.DllNotFoundException或初始化失败。
数据库文件路径要写对
MAUI 没有“默认数据库目录”，必须手动拼出可写路径。推荐做法是建一个
Constants.cs：
public static class Constants
{
public const string DatabaseFilename = "appdata.db3";
public static string DatabasePath => Path.Combine(FileSystem.AppDataDirectory, DatabaseFilename);
}
注意：
FileSystem.AppDataDirectory在各平台自动指向安全私有目录（如 Android 的
/data/data/{package}/files/），千万别硬编码路径或用 Environment.GetFolderPath。
推荐用异步连接 + 延迟初始化
新建一个
DatabaseService.cs，封装连接和表初始化逻辑： 用
SQLiteAsyncConnection而非同步连接，避免阻塞 UI 线程 在构造函数里不做实际初始化，改用
async Task Init()方法按需创建连接和表 首次调用前检查
Database == null，防止重复创建 调用
CreateTableAsync<t>()</t>确保表存在（含主键、索引等基础结构）
示例关键代码：
private SQLiteAsyncConnection _database;
public async Task Init()
{
if (_database != null) return;
_database = new SQLiteAsyncConnection(Constants.DatabasePath);
await _database.CreateTableAsync<User>();
}
增删改查尽量走异步方法
所有数据库操作都应使用带
Async后缀的方法，比如：
InsertAsync(obj)/
InsertAllAsync(list)
DeleteAsync(obj)/
DeleteAsync(id)（需先查再删，或自定义 SQL）
UpdateAsync(obj)
Table<t>().Where(...).ToListAsync()</t>或
FirstOrDefaultAsync()
别用同步方法（如
Insert()），尤其在页面加载或按钮点击中，否则 UI 会卡顿甚至 ANR（Android）。
基本上就这些。跑通一次后，后续加表、改字段、做迁移，都是在这个基础上扩展。
