用途：为 .NET MAUI 应用添加 SQLite 本地数据库存储，资料基于 sqlite-net-pcl，整理常见陷阱与最佳实践。
包选择：必须使用 sqlite-net-pcl 与 SQLitePCLRaw.bundle_green，不要误用 Microsoft.Data.Sqlite、sqlite-net 或 SQLitePCL.raw，它们 API 不兼容。示例：<PackageReference Include="sqlite-net-pcl" Version="1.9." /> 与 <PackageReference Include="SQLitePCLRaw.bundle_green" Version="2.1." />。
数据库路径：使用 FileSystem.AppDataDirectory 而非 Environment.GetFolderPath，后者在部分 MAUI 目标上不可用。
连接管理：SQLiteAsyncConnection 对同一文件的多个实例非线程安全，应通过 DI 注册为单例并懒初始化，只创建一次连接。初始化时执行 PRAGMA journal_mode=WAL; 并调用 CreateTableAsync<T>() 建表。
常见错误：忘记启用 WAL 会导致读写相互阻塞；在连接打开时移动、复制或删除数据库文件会造成数据损坏，必须先关闭连接再操作文件。
平台注意：iOS 上 FileSystem.AppDataDirectory 会同步到 iCloud，如需避免备份可改用 FileSystem.CacheDirectory。
保存模式：判断 Id != 0 则 Update，否则 Insert。多表则在懒初始化中统一添加所有 CreateTableAsync 调用。
性能建议：批量写入使用 RunInTransactionAsync 事务；对频繁查询列加 [Indexed]，尤其是外键；避免对大表直接 ToListAsync()，改用 Where 过滤与分页；复杂查询可用 QueryAsync<T> 原始 SQL。
本资料未提供完整服务实现、常量定义与数据模型模板，相关内容参见其 references/sqlite-database-api.md。