Flutter依赖地狱：AGP版本冲突与Gradle下载陷阱的实战解法

三年前首次接触Flutter，我被其热重载机制震撼。与Compose相比，Flutter的即时刷新速度更快，在Android设备上几乎零延迟见到代码变更。这种开发体验让我毫不犹豫地投入Flutter怀抱。

然而，随着项目规模扩大，依赖地狱的门逐渐敞开。

AGP版本兼容性：插件生态的隐形地雷

Flutter插件对AndroidGradlePlugin和AGP版本的向下兼容性问题，是每个开发者迟早会遇到的第一道坎。当你升级某个插件后，构建日志中突然出现AARmetadata检查失败的报错：

Dependency 'androidx.browser:browser:1.9.0' requires Android Gradle plugin 8.9.1 or higher. This build currently uses Android Gradle plugin 8.7.3.

此时面临两个选择：升级AGP版本，或者降级插件版本。升级AGP风险极高，可能引发其他插件连锁反应。降级插件则可能遇到该插件所有历史版本都无法适配当前环境的尴尬局面。以url_launcher为例，当所有低版本都无法兼容时，你只能被迫选择升级AGP。

网络下载陷阱：storage.flutter-io.cn镜像的不稳定性

选择升级AGP后，更漫长的等待开始了。Gradle构建时间以小时计，而你根本不知道它在后台下载什么。真正的问题出现在release构建阶段：Flutter引擎jar文件从国内镜像下载时频繁超时，导致构建彻底失败。

典型的错误日志显示jar文件下载不完整：expected38,957,021bytes，实际只收到3,440,640bytes。Gradle自动重试机制形同虚设，构建在20分钟后再次失败。

实战解决方案：清除缓存与网络切换

解决方案异常简单却行之有效。首先清除Gradle缓存中损坏的下载文件：

删除${USERPROFILE}/.gradle/caches/transforms-*和${USERPROFILE}/.gradle/caches/modules-2/files-2.1/io.flutter目录下的所有内容。然后重新运行构建命令。

如果镜像源持续不稳定，建议切换网络环境或使用VPN。从镜像下载的Flutter引擎jar文件会被Gradle缓存，后续构建无需重新下载。

坑踩多了，自然总结出规律：Flutter生态成熟度高，但依赖管理仍需开发者具备一定的Android构建系统知识。提前了解AGP与插件的兼容矩阵，可以有效规避这类问题。