解决Unity集成Flutter配置缺失：No Matching Configuration

2025-01-03 07:26:42

解决Unity集成到Flutter时配置缺失问题

当尝试将Unity项目作为组件集成到Flutter应用时，可能会遇到 “No matching configuration of project :unityLibrary was found” 的错误。这个错误通常指示Gradle无法找到正确的配置来构建unityLibrary模块。问题通常与依赖配置，以及Unity构建生成的组件与Flutter项目配置的不匹配有关。本文将分析此问题并提供详细的解决方案。

问题分析

此错误消息的核心是Gradle在处理依赖关系时遇到了难题。具体来说，app模块的依赖项要求特定属性的unityLibrary组件，比如针对Android优化的API，构建类型为debug，特定的Android Gradle插件版本，和Kotlin平台类型等。然而，Gradle无法在unityLibrary模块找到匹配这些要求的配置。这可能由以下几个原因造成：

Unity 构建设置不正确 : Unity项目导出的Android库配置不完整，缺少构建所需的属性和配置。特别是针对debug和release类型的配置。
Gradle配置错误 : unityLibrary 的模块级build.gradle文件配置有误，或者缺失必要的属性声明。
Android Gradle 插件版本冲突 : Flutter项目和 Unity 项目所使用的 Android Gradle 插件版本不一致可能引发配置不兼容问题。
构建缓存 : Gradle可能使用了缓存中的旧配置信息，从而导致不匹配。

解决方案

以下是一些解决这个问题的方案，可逐步尝试。

1. 检查Unity导出的Gradle配置

确认Unity导出为 Android 库时包含了必要的构建类型配置，尤其注意debug模式的配置，在unityLibrary/build.gradle或 unityLibrary/unityLibrary.gradle (文件名取决于unity 版本) 中：

操作步骤 ：

打开 unityLibrary/build.gradle 或者unityLibrary/unityLibrary.gradle 。
寻找类似android { buildTypes {... } } 代码块
如果发现没有 debug 或者 release 对应的配置, 手动添加如下示例配置. 注意，具体的配置，需要按照 Unity 的实际情况调整，比如添加 ndk{...} 代码块设置so库文件的配置，比如代码优化器，代码混淆配置等。

android {
   ...
   buildTypes {
       debug {
          //可按照实际需要修改 debug 配置, 如下面一些可选示例:
         minifyEnabled false
         proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-unity.txt'
        
        //设置 so 库文件目录， 例如
       ndk {
            abiFilters  'armeabi-v7a', 'arm64-v8a'
        }

       }
       release {
           //可按照实际需要修改 release 配置， 如下面一些可选示例:
           minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-unity.txt'
        
           ndk {
              abiFilters 'armeabi-v7a', 'arm64-v8a'
          }

         //例如签名
          signingConfig signingConfigs.release
       }
   }
}

代码说明 :

buildTypes: 配置构建类型的容器，包含 debug 和 release 配置。
debug: debug模式下的构建配置，包含 minifyEnabled ，是否启动代码优化，以及指定代码混淆规则的 proguardFiles
release：发布版本的构建配置。同样配置了 minifyEnabled 和 proguardFiles
ndk : 设置so 库架构信息, 不同unity 版本默认可能设置不同

额外建议: ：

如果没有添加签名， release 版本默认会用 debug 版本的签名，这在发布版本时候一定要注意替换，或者明确在debug 和 release 添加 signingConfig 配置。

2. 清理和重建Gradle项目

Gradle 构建过程中可能存在缓存问题。清理构建缓存，强制Gradle重新解析依赖和构建。

操作步骤 ：

打开终端或命令行界面。
进入 Flutter 项目的android目录。
运行以下Gradle命令:
```
  ./gradlew clean
```
或（在 Windows 环境下）
```
  gradlew.bat clean
```
重新构建Flutter项目

 flutter build apk

或

   flutter run

原理：
* clean 任务会清除项目中所有build目录下的构建输出，强制Gradle下次编译时重新生成这些文件。避免旧的依赖缓存或构建配置影响构建。

安全提示 ：

在清理之前，如果有正在编辑的java代码文件，注意备份或者保存文件，避免构建过程中删除尚未保存的文件。
* 构建缓存的清理可能会导致编译时间增长，耐心等待构建过程完成。

3. 同步 Gradle 配置

确保Flutter项目的根目录android/settings.gradle配置文件正确地引用了 unityLibrary，并指定了正确的项目路径。如果发现配置不匹配或者路径不对，一定要及时修改，参考前面给出的 include 配置信息.

include ":unityLibrary"
include ":app"

project(":unityLibrary").projectDir = new File("../unity/unityLibrary")

原理

include ':unityLibrary' : 告知 Gradle 项目包含名为 'unityLibrary' 的模块。
project(':unityLibrary').projectDir: 将 unityLibrary 的项目目录设置为相对路径 ../unity/unityLibrary ，从而在构建过程中正确引用对应的代码文件。

安全建议 :

建议使用相对路径引用 Unity 导出模块，这样更加方便地移动代码仓库。
确认导出的路径是否与实际Unity 项目路径一致，特别是检查项目名称拼写是否正确。

4. 检查Android Gradle 插件版本

如果问题仍然存在，可能是因为Android Gradle插件版本不兼容。Flutter项目使用的插件版本和 Unity项目导出的Android 库的 Gradle 插件版本可能存在差异，需要强制修改 unity 项目使用的 Gradle 插件版本号。

操作步骤 ：

在 Unity 项目的 unityLibrary/build.gradle 或者 unityLibrary/unityLibrary.gradle 文件中，查找dependencies代码块, 并更新对应的 gradle 插件版本, 使用跟 Flutter 一致的版本

```gradle
dependencies {
    classpath 'com.android.tools.build:gradle:7.3.0' // 假设当前flutter项目使用的插件版本
}

```

**代码说明** :
*  `classpath` 指定了Gradle 构建脚本使用的依赖插件， 如果跟Flutter项目不一致则会出现不兼容的情况

同时在 Flutter 的android/build.gradle 也查找和修改对应的 Gradle插件版本号

```gradle
  dependencies {
    classpath 'com.android.tools.build:gradle:7.3.0'  //确保这里的版本号也匹配
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    classpath "com.google.gms:google-services:$google_services_version"
  }

```

额外提示
* Gradle 插件版本会影响整个项目对 Java 代码的支持度，所以应该尽可能统一项目所有模块的 Gradle插件版本，避免因插件版本不兼容导致的异常错误

安全提示
* 升级或者降低 Android Gradle 插件版本都可能存在潜在风险。建议先备份项目，仔细测试并验证构建和运行是否稳定后在进行代码修改。
* 如果版本兼容性存在问题，建议优先升级或者统一 Gradle 插件版本，而不是使用低版本或者降级 Android 插件的版本。
* 可以根据具体的Gradle版本信息，或者在 Android studio 建议的版本号进行插件的版本配置.

5. 强制声明正确的编译属性

如果 unityLibrary 项目缺少某些特定编译配置，例如 api , android platform type ，则在 Flutter 主应用的 build.gradle 手动设置

操作步骤 ：

打开 Flutter 项目 android/app/build.gradle 文件
在 dependencies 代码块里面添加依赖，添加的时候需要指定要兼容的目标配置。这里设置 configuration ="debugApi". 根据自己的需要修改 configuration 的类型。

 dependencies {
       implementation (project(':unityLibrary')) {
          attributes {
              attribute(org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE, objects.named(org.gradle.api.attributes.Usage, org.gradle.api.attributes.Usage.JAVA_API));
             attribute(com.android.build.api.attributes.BuildTypeAttr.ATTRIBUTE,objects.named(com.android.build.api.attributes.BuildTypeAttr, "debug") );
            attribute(org.jetbrains.kotlin.platform.type, objects.named(org.jetbrains.kotlin.platform.type, "androidJvm") );
         }

      configuration="debugApi"
   }
     implementation 'androidx.multidex:multidex:2.0.1'

}
 ```

**代码说明** :
 * `attributes{}`  为添加属性配置, 这里通过强制修改 attributes 的值，强制要求 Gradle 兼容  unity 项目,  包括 使用 api , 使用 debug 配置以及指定平台类型是 AndroidJVM。

**额外说明:** 
  * 上面只是一个强制修改 attributes 值的示例代码。 对于特定平台、特定版本、以及特殊配置要求，  属性的值可能都需要更改
 * 在实际环境中，  可能需要仔细检查 build log 输出, 定位属性配置要求.  同时， 为了兼容不同的 Unity 项目， 添加的兼容属性需要按需添加

## 结论

解决 “No matching configuration of project :unityLibrary was found”  错误需要仔细检查Unity 导出配置、Gradle构建配置和依赖关系。通过按步骤检查和修正， 可以有效地解决 Gradle 构建时的配置冲突，将 Unity 项目顺利集成到 Flutter 应用。

如问题依旧，可逐步尝试不同解决方案，并仔细检查构建输出和报错信息。同时建议参考Unity和Flutter的官方文档，以确保环境和工具链的配置正确无误。