Flutter报FAILURE: Build failed with an exception构建失败求助

问题背景 #

• 例行检查运行Flutter应用时突发构建异常，距上次成功构建间隔仅5分钟，期间未对项目做任何代码修改，尝试公开的通用修复方案均无效。
• 表层报错为Gradle执行:app:compileFlutterBuildDebug任务失败，flutter doctor全量检测无异常。

表层报错信息 #

FAILURE: Build failed with an exception.

* Where:
Script '/Users/Documents/flutter/packages/flutter_tools/gradle/flutter.gradle' line: 1156

* What went wrong:
Execution failed for task ':app:compileFlutterBuildDebug'.
> Process 'command '/Users/Documents/flutter/bin/flutter'' finished with non-zero exit value 1

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.

BUILD FAILED in 42s
Exception: Gradle task assembleDebug failed with exit code 1

环境检测结果 #

[✓] Flutter (Channel stable, 3.0.2, on macOS 12.3.1 21E258 darwin-x64)
    • Flutter version 3.0.2 at /Users/Documents/flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision cd41fdd495 (6 days ago), 2022-06-08 09:52:13 -0700
    • Engine revision f15f824b57
    • Dart version 2.17.3
    • DevTools version 2.12.2

[✓] Android toolchain - develop for Android devices (Android SDK version 32.1.0-rc1)
    • Android SDK at /Users/Library/Android/sdk
    • Platform android-32, build-tools 32.1.0-rc1
    • Java binary at: /Applications/Android Studio.app/Contents/jre/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment (build 11.0.11+0-b60-7590822)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 13.4.1)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • CocoaPods version 1.11.3

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2021.1)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Java version OpenJDK Runtime Environment (build 11.0.11+0-b60-7590822)

[✓] VS Code (version 1.66.0)
    • VS Code at /Users/Downloads/Visual Studio Code.app/Contents

[✓] Connected device (3 available)
    • macOS (desktop)   • macos       • darwin-x64     • macOS 12.3.1 21E258 darwin-x64
    • Chrome (web)      • chrome      • web-javascript • Google Chrome 102.0.5005.61

[✓] HTTP Host Availability
    • All required HTTP hosts are available

• No issues found!

排查修复步骤 #

当前给出的报错是Gradle层的通用封装报错，没有暴露真实失败原因，按以下顺序排查即可：

• 第一步：全量清理构建缓存
  无代码改动突发构建失败90%以上是缓存损坏导致，在项目根目录依次执行命令：

  flutter clean
  rm -rf .dart_tool/
  rm -rf android/.gradle/
  rm -rf android/app/build/
  rm -rf ios/Pods/ ios/Podfile.lock
  flutter pub get
  

  执行完成后关闭所有IDE进程，重新打开项目尝试构建。
• 第二步：抓取详细错误日志
  缓存清理后仍报错的，执行带verbose参数的构建命令输出全量日志：

  flutter run -v
  

  重点查看日志中compileFlutterBuildDebug节点前的输出，常见根因包括：
  • 本地pub缓存的第三方依赖文件损坏
  • Android SDK build-tool 32.1.0-rc1预览版存在兼容bug
  • 系统更新后目录权限变更导致临时文件写入失败
  • 资源文件名称存在特殊字符导致编译失败
    定位到具体错误点后针对性修复即可。
• 第三步：修复Flutter SDK全局缓存
  如果详细日志中没有明确的项目层错误，执行命令强制重建Flutter SDK缓存：

  flutter precache --force
  flutter doctor --android-licenses
  

• 第四步：修复目录权限
  macOS系统偶发在后台更新后重置用户目录权限，执行命令给对应目录赋权：

  sudo chmod -R 755 /Users/Documents/flutter/
  sudo chmod -R 755 你的项目根目录绝对路径
  

  执行后重启设备再尝试构建。

高频踩坑点：当前环境使用的是32.1.0-rc1预览版build-tool，若上述步骤操作后仍然报错，可在Android SDK管理器中卸载该预览版，安装32.0.0稳定版build-tool后重试。

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