Flutter重运行报Gradle构建失败需重复clean问题排查

首次运行Flutter项目触发Gradle构建失败，报错如下：

Running Gradle task 'assembleDebug'...

FAILURE: Build failed with an exception.

* Where:
Script 'C:\src\flutter\flutter\packages\flutter_tools\gradle\flutter.gradle' line: 1102

* What went wrong:
Execution failed for task ':app:compileFlutterBuildDebug'.
> Process 'command 'C:\src\flutter\flutter\bin\flutter.bat'' 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 3m 6s
Exception: Gradle task assembleDebug failed with exit code 1

执行flutter clean或手动删除build文件夹，再运行flutter pub get后重新启动可以编译成功，编译过程会输出多段deprecated API、unchecked操作的提示，最终apk成功生成并安装到设备，但会抛出文件系统异常：

Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: C:\src\flutter\flutter\.pub-cache\hosted\pub.dartlang.org\firebase_analytics-9.1.12\android\src\main\java\io\flutter\plugins\firebase\analytics\FlutterFirebaseAnalyticsPlugin.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
Note: C:\src\flutter\flutter\.pub-cache\hosted\pub.dartlang.org\firebase_dynamic_links-4.3.1\android\src\main\java\io\flutter\plugins\firebase\dynamiclinks\FlutterFirebaseDynamicLinksPlugin.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
Note: C:\src\flutter\flutter\.pub-cache\hosted\pub.dartlang.org\firebase_messaging-11.4.4\android\src\main\java\io\flutter\plugins\firebase\messaging\JobIntentService.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: C:\src\flutter\flutter\.pub-cache\hosted\pub.dartlang.org\local_auth-1.1.11\android\src\main\java\io\flutter\plugins\localauth\LocalAuthPlugin.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
√  Built build\app\outputs\flutter-apk\app-debug.apk.
Installing build\app\outputs\flutter-apk\app.apk...
W/FlutterActivityAndFragmentDelegate(23939): A splash screen was provided to Flutter, but this is deprecated.
Debug service listening on ws://127.0.0.1:51876/WyzGLXWyh3M=/ws
Finished with error: FileSystemException: Directory listing failed, path = 'C:\Users\USER\Downloads\Project\Tutorials\Documets\Flutter Tech Project\project1\New Code\dart_files\skyline-user\build\flutter_plugin_android_lifecycle\generated\source\buildConfig\debug\io\flutter\plugins\flutter_plugin_android_lifecycle\*' (OS Error: The system cannot find the path specified.
, errno = 3)

该场景下应用可以正常运行，但每次重新启动项目都会复现初始构建失败问题，必须重复clean+pub get流程才能启动。

• 核心原因是Windows系统默认的260字符路径长度限制。当前项目存放的目录层级过深，build目录下自动生成的插件嵌套路径总长度已经超过系统默认限制，Gradle做增量构建时无法正常读写深层目录的文件，直接导致构建任务中断。
• 执行flutter clean后会清空所有旧的构建缓存，首次全量构建时Gradle按顺序生成目录、打包apk，在路径超限前就能完成apk编译输出，所以可以安装成功；但构建收尾阶段遍历深层生成文件时还是会触发路径不存在的异常，不过此时核心打包流程已经走完，不影响应用安装。
• 编译过程中输出的所有Note:开头的提示、废弃启动页警告都属于第三方插件、项目配置的正常提示，和构建失败问题无关，不需要单独处理。

按有效性优先级排序操作：

• 优先缩短项目存放路径：把整个项目文件夹移动到层级更浅的根目录，比如C:\dev\skyline-user，确保项目最深层子路径总长度不超过240字符。移动完成后执行一次flutter clean、flutter pub get，后续增量构建就不会再复现问题，这是最稳定无兼容问题的方案。
• 若不想移动项目，可开启Windows长路径支持：
  • 按Win+R输入gpedit.msc打开本地组策略编辑器
  • 依次进入「计算机配置 > 管理模板 > 系统 > 文件系统」
  • 找到「启用Win32长路径」选项，设置为已启用，保存后重启电脑生效
  • 确认本地Flutter版本≥3.0、项目使用的Gradle版本≥7.0，两个版本已默认适配长路径特性
• 额外兼容处理：
  • 把项目路径中带空格的目录名改成无空格的英文名称，比如把Flutter Tech Project改为flutter_tech_project，避免旧版Gradle插件对带空格路径的兼容问题
  • 不要把项目放在下载目录、桌面这类受系统权限管控的路径下，避免安全软件拦截Gradle的文件读写操作

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