Flutter使用shared_preferences包时出现Gradle assembleDebug构建失败问题

报错信息汇总 #

• 构建过程异常终止，出错位置为Flutter SDK路径下的D:\flutter\packages\flutter_tools\gradle\flutter.gradle脚本第1156行
• 核心失败原因：任务:app:compileFlutterBuildDebug执行失败，Gradle任务assembleDebug退出码为1

进程执行命令D:\flutter\bin\flutter.bat结束，返回非零退出值1
通用日志提示：构建时添加--stacktrace参数可获取堆栈追踪信息；添加--info或--debug参数可输出更多日志；添加--scan参数可获取完整构建分析详情

• 本次构建总耗时21秒
  报错截图

解决步骤 #

按顺序执行以下操作，每步完成后重新尝试构建，验证问题是否修复：

• 清理损坏缓存，重新拉取依赖
  在项目根目录终端依次执行以下命令：

  flutter clean
  flutter pub cache repair
  flutter pub get
  

  可解决临时缓存损坏、依赖文件拉取不完整导致的通用构建错误。
• 校验插件与SDK版本匹配性
  打开项目根目录下的pubspec.yaml文件，检查shared_preferences的版本号：Flutter 3.x稳定渠道需使用不带dev、beta标识的正式发布版本，禁止使用0.5.x及更早的过旧版本，也不要盲目使用未适配稳定版的预发布版本。
• 修正Android端构建配置
  打开android/app/build.gradle文件，找到defaultConfig配置块，检查minSdkVersion配置：shared_preferences 2.x及以上正式版本要求最低minSdk为16，推荐直接设置为21，兼容绝大多数主流Flutter插件的版本要求，配置参考：

  defaultConfig {
      applicationId "你的应用包名"
      minSdkVersion 21
      targetSdkVersion 34
      versionCode 1
      versionName "1.0"
  }
  

  同时确认项目的Gradle版本、Android Gradle插件版本、Kotlin版本与当前安装的Flutter SDK版本要求对齐，版本差过大也会导致插件编译失败。
• 拉取详细日志定位具体根因
  上述步骤未解决问题时，在项目根目录执行带调试参数的构建命令，获取具体错误点：

  flutter run --debug --stacktrace
  

  无需关注最外层的通用构建失败提示，直接查看堆栈日志中与shared_preferences关联的具体报错，常见根因包括AndroidX依赖重复冲突、AndroidManifest配置冲突、Kotlin版本不匹配等，都会在详细日志中明确标注。
• 处理依赖冲突
  若日志提示存在AndroidX依赖版本冲突，在android/app/build.gradle的android配置块中添加强制版本对齐规则，统一冲突依赖的版本号即可。

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