启用实验性API需两步：加@OptIn注解且在build.gradle.kts中配置kotlinOptions.freeCompilerArgs += "-Xopt-in=xxx"，二者缺一不可，否则编译报错。
启用实验性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。
-
@OptIn必须写在**使用该 API 的声明上方**，不是 import 上方，也不是文件顶部 - 如果是 top-level 函数，
@OptIn就贴在fun前面；如果是类里方法，就贴在fun前面，不是 class 前面 - 如果函数返回类型或参数类型是实验 API（比如返回
Provider<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 提示的红色波浪线落在哪一行、哪个类型上。
