Flutter 项目 AGP 8.x 升级踩坑实录

tbit
754 阅读4分钟

Flutter 项目 AGP 8.x 升级踩坑实录与终极解决方案

一、 背景

在将一个大型 Flutter 项目升级到较新版本后，Android 端的编译环境被强制升级到了 Android Gradle Plugin (AGP) 8.x 版本。这次升级引发了一系列连锁的、看似无穷无尽的编译失败，本文档详细记录了解决这些问题的全过程。

二、 核心问题：AGP 8.x 的两大破坏性变更

所有问题的根源，都来自于 AGP 8.x 对 Gradle 脚本提出的两项新的、严格的要求：

  1. 强制命名空间 (Mandatory Namespace): 不再允许从 AndroidManifest.xml 中隐式推断模块的包名，要求所有 Android 库模块必须在各自的 build.gradle 文件中显式声明 namespace。
  2. 更严格的 Gradle 脚本语法: 对 build.gradle 文件中代码块的摆放位置、声明方式有了更严格的规定，旧的、不规范的写法将直接导致编译失败。

三、 第一阶段战役：Namespace not specified

这是我们遇到的第一个，也是持续时间最长的“拦路虎”。

问题现象

在执行 flutter run 时，编译失败，并轮流抛出以下错误，每次指向一个不同的插件：

  • A problem occurred configuring project ':app_plugin'. > Namespace not specified.
  • A problem occurred configuring project ':connectivity'. > Namespace not specified.
  • A problem occurred configuring project ':device_info'. > Namespace not specified.
  • A problem occurred configuring project ':flutter_keyboard_visibility'. > Namespace not specified.
  • ... 等等

关键难点：找到真正的 build.gradle 文件

我们很快意识到需要在插件的 build.gradle 中添加 namespace，但真正的挑战在于，这些插件并非项目中的本地文件，而是由 Flutter 的依赖管理系统下载并缓存的。

必须理解 Flutter 的依赖缓存机制：

  • Git 依赖: 像 app_plugin 这样通过 Git URL 引入的插件，被缓存在： ~/.pub-cache/git/
  • 公共库依赖: 像 connectivity 这样从 pub.dev 下载的插件，被缓存在： ~/.pub-cache/hosted/pub.dev/

终极解决方案

我们采取了一套标准化的“三步走”战术，对每一个报错的插件都执行了一遍：

  1. 定位插件: 根据错误日志中提供的插件名（如 :connectivity），在上述对应的 .pub-cache 目录中找到其文件夹（如 connectivity-3.0.6）。
  2. 找到包名: 打开插件目录下的 android/src/main/AndroidManifest.xml 文件，完整复制 package="..." 属性的值。
  3. 添加命名空间: 打开插件目录下的 android/build.gradle 文件，在 android { 代码块的最上方，添加新的一行，并将刚刚复制的包名粘贴进去。 
    android {
    namespace "io.flutter.plugins.connectivity" // 添加的命名空间
    compileSdkVersion 34
    // ...
}

我们通过重复这套战术，逐一攻克了所有报 Namespace 错误的插件。

四、 第二阶段战役：Gradle 语法校准

在解决了所有 Namespace 问题后，我们迎来了新的、也是最后一个敌人。

问题现象

编译推进到 :flutter_mpay 插件时，抛出了一个全新的错误：

A problem occurred evaluating project ':flutter_mpay'.
> Could not find method kotlinOptions() for arguments [...] on extension 'android' of type com.android.build.gradle.LibraryExtension.

根本原因：插件内的“假司令部”

即便检查发现 kotlinOptions 代码块的位置是正确的，错误依然存在。经过对该插件 build.gradle 文件的审查，我们发现了真正的根源：

该插件的 build.gradle 中包含了 buildscript { ... } 和 rootProject.allprojects { ... } 代码块。这两个代码块是项目级的“总司令部”，只应存在于项目最顶层的 android/build.gradle 文件中。当一个子模块（插件）也尝试定义它们时，就造成了严重的配置冲突，让新的 AGP 引擎无法正确解析脚本。

终极解决方案

对 :flutter_mpay 的 build.gradle 文件进行“拨乱反正”，彻底删除文件顶部的 buildscript { ... } 和 rootProject.allprojects { ... } 两个代码块。

清理后，该文件应以 group '...' 或 apply plugin: '...' 开头，不再包含任何项目级的配置。这使得插件能够正确地继承来自主项目的统一 Gradle 配置。

五、 技术插曲：device_info_plus 插件的正确用法

在解决编译问题的间隙，我们尝试使用 device_info_plus 插件获取设备 ID。

  • 遇到的问题: 使用 androidInfo.androidId 获取安卓设备ID时，编译器报错 The getter 'androidId' isn't defined for the type 'AndroidDeviceInfo'.
  • 原因: device_info_plus 插件在新版本中为了统一API，将安卓的设备ID属性从 androidId 更名为了 id。
  • 正确用法: 
    final AndroidDeviceInfo androidInfo = await deviceInfoPlugin.androidInfo;
deviceId = androidInfo.id; // 使用 .id 获取

六、 总结与启示

  1. 系统性风险: Flutter/Android 的大型版本升级是一项系统性工程，会一次性暴露项目中所有不规范的、陈旧的依赖插件的问题。
  2. 日志是关键: 仔细阅读 Gradle 的错误日志，是定位问题的最快途径。Namespace 和 Gradle Syntax 是 AGP 8.x 升级中最常见的两类问题。
  3. 缓存是核心: 理解并敢于修改 .pub-cache 中的文件，是解决由第三方插件引发的编译问题的核心技能。
  4. 长远之计: 直接修改缓存是临时的“热修复”。长远来看，最佳实践是：
    • Fork 这些有问题的插件到自己的 Git 仓库。
    • 在自己的仓库中修复这些问题。
    • 在 pubspec.yaml 中将依赖指向自己修复后的 Git 仓库。
    • 或者，寻找社区中已经适配新版本、仍在积极维护的替代插件。
avatar
文章
阅读
粉丝