.NET MAUI安卓端创建SQLite连接时抛出FileNotFoundException异常

问题场景 #

开发.NET MAUI应用时，执行如下代码创建SQLite连接：

db = new SQLiteConnection(databasePath);

该代码在Windows平台可正常运行，且此前在Xamarin.Forms框架下双平台运行均无异常，迁移到.NET MAUI后在安卓平台运行时触发如下错误：

System.IO.FileNotFoundException: 'Could not load file or assembly 'SQLitePCLRaw.provider.dynamic_cdecl, Version=2.0.4.976, Culture=neutral, PublicKeyToken=b68184102cba0b3b' or one of its dependencies.'

排查路径与对应解决方案 #

• 检查NuGet依赖完整性
  从Xamarin.Forms迁移到MAUI单项目结构时，最常见的问题是依赖包漏装或者版本不匹配。不要只安装sqlite-net-pcl核心包，需要确认项目中已安装和报错版本完全一致的SQLitePCLRaw.provider.dynamic_cdecl包，检查包引用是否添加了安卓平台的排除规则，确保安卓目标框架下能正常还原该依赖。
• 显式初始化SQLite Provider
  安卓平台不会自动探测加载dynamic_cdecl对应的原生provider，不要依赖运行时的自动加载逻辑，在应用启动阶段（MauiProgram的构建流程、App构造函数均可）主动执行初始化代码：

  // 初始化SQLite通用组件
  SQLitePCL.Batteries_V2.Init();
  // 针对安卓平台显式指定使用e_sqlite3实现，避免动态查找程序集失败
  SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_e_sqlite3());
  

  初始化逻辑执行完成后，再创建SQLite连接实例。
• 排查安卓链接器裁剪问题
  MAUI安卓在Release模式下默认开启程序集裁剪，静态扫描时如果没有发现对SQLitePCLRaw.provider.dynamic_cdecl的显式引用，会直接把该程序集裁掉导致加载失败。
  临时把安卓项目的链接器行为调整为无重新编译测试，如果调整后错误消失，就说明是裁剪导致的。此时不需要永久关闭链接器，只需在项目中添加自定义链接器配置文件（生成操作设置为LinkDescription），添加规则保留SQLitePCLRaw相关程序集的所有类型不被裁剪即可。
• 清理编译缓存重新部署
  项目迁移、版本升级过程中，obj、bin目录下的旧编译缓存、设备上残留的旧部署包都可能导致依赖加载异常。先全量清理解决方案，手动删除所有项目下的obj、bin文件夹，重新还原NuGet包后，卸载设备上已安装的旧版本应用，再重新编译部署测试。

内容的提问来源于stack exchange，提问作者Jim