Flutter项目编译运行时报Gradle构建失败错误如何解决

你当前看到的Gradle报错是表层错误，真实的编译失败原因被日志吞了，按以下步骤逐一排查修复：

第一步：先获取真实错误日志 #

在项目根目录执行命令输出完整编译日志，定位具体根因：

flutter build apk --debug --stacktrace

日志中Process 'command 'flutter.bat'' finished with non-zero exit value 1字段之前的报错内容，就是导致编译失败的直接原因，常见根因包括缓存损坏、配置不兼容、资源冲突、代码语法错误、依赖版本不匹配。

第二步：清理全链路构建缓存 #

Flutter升降级后出现的编译问题90%和缓存不兼容有关，依次执行以下命令清理：

# 清理Flutter项目构建缓存
flutter clean
# 修复pub全局缓存损坏问题
flutter pub cache repair
# 进入Android目录清理Gradle构建缓存
cd android
# Windows系统执行下一行
gradlew.bat clean
# Mac/Linux系统执行下一行
# ./gradlew clean
# 回到项目根目录重新拉取依赖
cd ..
flutter pub get

清理完成后重新尝试编译。

第三步：校验Android构建配置兼容性 #

Flutter 2.10.0对Android构建链的版本有固定匹配要求，手动改过配置或者升降级SDK后很容易出现版本不匹配：

• 打开android/build.gradle文件，确认kotlin_version为1.5.31，Android Gradle插件版本为com.android.tools.build:gradle:7.0.2
• 打开android/gradle/wrapper/gradle-wrapper.properties文件，确认distributionUrl对应的Gradle版本为7.2，版本不对直接修改为对应值即可。

注：flutter doctor中提示的Visual Studio 2017版本过低是Windows桌面开发的依赖项，如果你当前编译的是Android、Web端安装包，这个提示完全不影响编译，不需要专门处理。

第四步：针对性修复具体错误 #

如果清理缓存、校验配置后仍然报错，对照第一步拿到的完整日志处理：

• 若提示资源合并失败：检查android/app/src/main/res目录下的资源文件，文件名不能包含大写字母、特殊字符，排查是否和第三方依赖存在重名资源
• 若提示Dart编译错误：日志会直接标注出错的文件路径和行号，对应修正语法错误即可
• 若提示第三方依赖兼容错误：检查pubspec.yaml中的依赖版本，不要使用仅支持Flutter 3.x的高版本依赖，替换为2022年2月（Flutter 2.10发布时间）前后的稳定适配版本

极端场景修复 #

如果以上步骤全部执行后问题仍然存在，直接删除本地Flutter SDK目录，重新解压Flutter 2.10.0稳定版完整包，重新配置环境变量，排除升降级过程中SDK文件损坏的问题。

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