Gradle Kotlin项目怎么启用实验性API-java教程-PHP中文网

启用实验性api需两步：加@optin注解且在build.gradle.kts中配置kotlinoptions.freecompilerargs += "-xopt-in=xxx"，二者缺一不可，否则编译报错。

gradle kotlin项目怎么启用实验性api

启用实验性API需要两步：加注解 + 开编译器选项

Gradle Kotlin项目里用到 @RequiresOptIn 标记的 API（比如某些 AGP 10.0 的 androidComponents 扩展、Kotlin 标准库里的 ExperimentalTime），光写 @OptIn(XXX::class) 不够，编译器会直接报错：「This declaration is experimental」。必须同时在模块级 build.gradle.kts 中显式开启对应 opt-in。

在 gradle.properties 或构建脚本中设置 -Xopt-in 编译器参数，例如：

compileKotlin {
    kotlinOptions {
        freeCompilerArgs += "-Xopt-in=kotlinx.coroutines.ExperimentalCoroutinesApi"
        freeCompilerArgs += "-Xopt-in=androidx.compose.runtime.ExperimentalComposeApi"
    }
}

如果用的是 Kotlin DSL（build.gradle.kts），推荐写成更清晰的 list 形式，避免字符串拼接出错
多个 opt-in 可以并列添加，但每个都得独立写一行 freeCompilerArgs +=，不能用逗号连写
注意路径大小写：比如 kotlinx.coroutines 不是 Kotlinx.Coroutines，拼错就白配了

AGP 10.0+ 的 androidComponents {} 怎么 opt-in

AGP 10.0 彻底弃用了 applicationVariants.all {} 这类急切式 API，改用延迟的 androidComponents {}。这个 block 本身是 @RequiresOptIn(AndroidGradlePluginApi::class) 的，官方没公开这个 annotation 类名，但实际要用的是 com.android.build.api.dsl.AndroidGradlePluginApi —— 它在 AGP 10.0+ 的 classpath 里，但不是 public API，所以必须用字符串形式传入：

在 build.gradle.kts 的 androidComponents 块外加 @OptIn 注解：

@OptIn(com.android.build.api.dsl.AndroidGradlePluginApi::class)
androidComponents {
    onVariants { variant ->
        variant.artifacts.setTaskInputToFinalZip(
            "release",
            project.tasks.named("assembleRelease")
        )
    }
}

或者更稳妥的做法：直接在 kotlinOptions 里加 -Xopt-in=com.android.build.api.dsl.AndroidGradlePluginApi
别试图 import 这个类——它被标记为 @VisibleForTesting，IDE 能跳转但编译会失败
如果用了自定义插件调用 androidComponents，那个插件的函数也得加 @OptIn，否则传播失败

常见错误：@OptIn 写错位置或漏掉作用域

很多人把 @OptIn 放在函数内部、或者只加在调用处却忘了加在声明处，结果还是编译不过。关键点在于：谁用了实验 API，谁就得 opt-in；如果封装了一层，封装函数也要 opt-in。

ChatLaw

ChatLaw是一款AI法律服务工具，北大开源的法律大模型和助手。

下载

@OptIn 必须写在**使用该 API 的声明上方**，不是 import 上方，也不是文件顶部
如果是 top-level 函数，@OptIn 就贴在 fun 前面；如果是类里方法，就贴在 fun 前面，不是 class 前面
如果函数返回类型或参数类型是实验 API（比如返回 Provider<directory></directory>），那这个函数本身也要 @OptIn
在 buildSrc 或自定义 Gradle 插件里用实验 API，同样要加 freeCompilerArgs，且插件的 build.gradle.kts 也得配

为什么 build.gradle.kts 里还要额外配置？

Kotlin 编译器不会自动扫描构建脚本里用到的实验 API，因为 build.gradle.kts 是作为 Kotlin 脚本运行的，其编译上下文和普通模块不同。Gradle 会把它当成一个独立的 Kotlin 源集处理，所以 @OptIn 注解只影响运行时行为，不参与编译期检查 —— 真正起效的是 -Xopt-in 参数。

不加 -Xopt-in，哪怕写了 @OptIn，Kotlin 编译器仍会拒绝编译
AGP 8.1+ 默认启用 Kotlin DSL，但没默认开任何 opt-in，这是设计使然：防止用户误用不稳定接口
如果你的项目同时有应用模块和 buildSrc，两个地方都要单独配 kotlinOptions
CI 环境容易漏掉这个配置，导致本地能过、CI 报错，建议把 freeCompilerArgs 提取为常量复用

最易忽略的一点：AGP 升级到 10.0 后，androidComponents 的回调参数类型（如 Variants、Variant）全变了，它们本身也是实验性的，意味着你读取 variant.name 或 variant.artifacts 都可能触发新的 opt-in 要求——别只盯着 block 名称，要看清楚 IDE 提示的红色波浪线落在哪一行、哪个类型上。