Gradle插件通过project.configurations.create()在apply阶段注册自定义依赖分组，需指定唯一名称、显式继承标准配置（如extendsFrom configurations.api），并设置isVisible=true、isCanBeResolved=true等属性以确保IDE识别与正确解析，避免覆盖AGP预置配置或在错误时机操作。
Gradle 插件本身不直接“创建依赖配置”，而是通过操作 Project.configurations 来声明和注册新的依赖分组（configuration），供下游项目在 dependencies 块中使用。关键在于：插件必须在 apply(Project) 阶段完成配置注册，且需明确其继承关系与可见性。
configurations.create() 声明新配置
最常用的方式是在插件的 apply 方法里调用 project.configurations.create()。注意不是 createIfNotExists —— 插件应保证幂等，但首次注册必须成功，否则下游 dependencies { myConf '...' } 会报错 “Unknown configuration”。
- 必须传入唯一 name，如
'apiOnly'；不能含空格或特殊字符 - 建议设置
extendsFrom，例如extendsFrom configurations.implementation，否则该配置默认不参与编译类路径，仅作声明用途 - 若希望该配置出现在 IDE 的依赖树中，需额外调用
configuration.isVisible = true和configuration.isCanBeResolved = true（可解析）或isCanBeConsumed = true（可消费）
让配置支持 implementation/api 语义
Android Gradle 插件（AGP）和 Java 插件都预置了标准生命周期配置（如 implementation、api）。自定义配置若想复用其行为（比如自动传递依赖、影响编译/运行时 classpath），不能只靠名字模仿，而要显式继承：
-
configurations.create('myApi') { extendsFrom configurations.api }→ 会把该配置下的依赖作为 API 暴露给消费者 -
configurations.create('myRuntimeOnly') { extendsFrom configurations.runtimeOnly }→ 仅加入运行时 classpath，不参与编译 - 错误做法：
configurations.create('api')—— 会覆盖 AGP 的原生api配置，导致模块间依赖失效
在插件中暴露配置供下游使用
单纯创建配置还不够，下游项目需要能识别并使用它。常见疏漏点：
- 插件未 apply
java或com.android.library等基础插件，导致configurations尚未初始化就调用create()，抛出IllegalStateException: Configurations cannot be created before project is configured - 配置名未文档化，下游写
myconf（小写）而插件注册的是myConf，报错Could not find method myconf() for arguments [...] - 未设置
configuration.attributes.attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage.class, Usage.JAVA_API))，导致在 Kotlin Multiplatform 或 Android 的 variant-aware 解析中被忽略
避免与 AGP 冲突的典型场景
在 Android 项目中开发自定义插件时，configurations 行为受 AGP 强约束：
- AGP 会在
afterEvaluate阶段重写部分配置的canBeResolved/canBeConsumed属性，所以不要在afterEvaluate里注册配置，应在apply直接注册 - 不要尝试修改
compileClasspath或runtimeClasspath这类聚合配置，它们由 AGP 动态生成；应继承自implementation等稳定基线 - 如果插件目标是 Android 库模块，务必检查
configurations.findByName('myConf')?.isVisible是否为true，否则 Android Studio 不会在 Project Structure → Dependencies 中显示该配置
真正难的不是写几行 create()，而是让配置在 Java/Kotlin/Android/KMM 多种上下文中保持行为一致，并被 IDE 正确索引 —— 这要求你清楚每种构建类型对 Configuration 生命周期和属性的隐式约定。
