Android Gradle 中的解决@Incubating 警告：externalNativeBuild 标记为不稳定的API

在使用 Kotlin DSL 编写 Android Gradle 构建脚本时，遇到一个这样的黄色警告：

'externalNativeBuild(kotlin.jvm.functions.Function1<? super com.android.build.api.dsl.ExternalNativeBuildFlags,kotlin.Unit>)' is marked unstable with @Incubating

出现在配置 Native C/C++ 部分：

externalNativeBuild {
    cmake {
        cppFlags += listOf("-std=c++17")
        abiFilters += listOf("arm64-v8a", "x86_64")
    }
}

@Incubating 注解是什么？

根据 Stack Overflow 上的解释：

@Incubating 注解表示该功能正在孵化中。这意味着该功能目前是一个正在进行的工作，可能随时会改变。所以不用担心，继续使用它，并在未来需要时进行更新。

重要提示：这不是一个错误，而是一个友好的警告，提醒你正在使用一个可能在未来版本中发生变化的 API。

为什么会出现这个警告？

Kotlin DSL vs Groovy DSL

这个警告主要在从 Groovy 迁移到 Kotlin DSL 后出现。根据 Stack Overflow 上的讨论：

在 Groovy 中不会显示这个警告，但 Kotlin DSL 的 lint 检查会检测到这些不稳定的 API。

这并不意味着功能本身有问题，只是 Kotlin DSL 的类型检查更加严格，能够检测到这些 @Incubating 注解。

externalNativeBuild 的现状

查看 Android Developers 官方 API 文档，你会发现 externalNativeBuild 相关的许多方法仍然标记为 @Incubating。

更令人困惑的是，根据这个 Stack Overflow 讨论：

即使在 Android 官方文档中，这些 API 也被推荐使用，但没有说明用什么来替代它们。似乎这些功能"永远处于孵化状态"，看不到稳定替代方案。

需要采取行动吗？

根据 Stack Overflow 上的建议：

只要你没有使用已弃用的功能，通常就可以正常使用。如果将来有什么改变或被弃用，你会通过编译错误或警告得到通知。

简而言之：这个警告不会影响：

✅ 代码编译
✅ 应用运行
✅ 功能正常性

解决方案

方案1：抑制整个文件的警告（推荐）

在你的 build.gradle.kts 文件顶部添加：

@file:Suppress("UnstableApiUsage")

android {
    // ...
    externalNativeBuild {
        cmake {
            path = file("CMakeLists.txt")
        }
    }
    
    defaultConfig {
        // ...
        externalNativeBuild {
            cmake {
                cppFlags += listOf("-std=c++17")
                abiFilters += listOf("arm64-v8a", "x86_64")
            }
        }
    }
}

方案2：针对特定代码块抑制

如果只想抑制特定代码块的警告：

android {
    // ...
    
    @Suppress("UnstableApiUsage")
    externalNativeBuild {
        cmake {
            cppFlags += listOf("-std=c++17")
            abiFilters += listOf("arm64-v8a", "x86_64")
        }
    }
}

方案3：直接忽略

如果你不介意 IDE 中的黄色警告，也可以直接忽略它。这个警告纯粹是提示性的。

其他常见的 @Incubating 警告

在使用 Kotlin DSL 时，你可能还会遇到其他类似的警告：

buildFeatures

buildFeatures {
    dataBinding = true
    viewBinding = true
}

好消息是，根据 Stack Overflow 的更新，buildFeatures 在 Android Gradle Plugin 7.1 中已经升级为稳定版。如果你使用的是较新版本的 AGP（目前稳定版是 8.x），这个警告应该不会出现。

defaultConfig、testOptions 等

类似的警告还会出现在：

defaultConfig - 相关讨论
testOptions - 相关讨论
dependencyResolutionManagement - 相关讨论

是否有稳定的替代 API？

遗憾的是，目前没有。

对于 externalNativeBuild，这就是 Android 官方推荐的配置方式。即使标记为 @Incubating，它已经在生产环境中使用多年，实际上非常稳定。

根据社区的共识：

这是官方标准做法
没有其他替代方案
已经经过大量实际项目验证

热门分类