Gradle Module Metadata 是通过 maven-publish 插件自动生成的 .module 文件，提供版本约束、可选依赖和平台兼容性等能力，需 Gradle ≥6.0、components.java 和显式 publication 配置；其完整性取决于 api/implementation 正确区分、optional 依赖标记及 enforcedPlatform 锁定 BOM 版本。
在 Java Gradle 项目中，发布元数据（Metadata）不是指“额外添加的描述信息”，而是指通过标准化、结构化的方式生成并发布 .module 文件（Gradle Module Metadata），配合 POM 或 Ivy 描述符，让依赖解析具备版本约束、可选依赖、平台兼容性等关键能力。它直接决定下游项目能否正确、稳定地消费你的库——尤其在多模块、BOM 或 Kotlin Multiplatform 场景下，缺失或配置不当会导致依赖丢失、传递失效、JVM 环境误判等问题。
启用并生成 Gradle Module Metadata
Gradle 默认在发布到 Maven 兼容仓库（如 Nexus、Artifactory、Maven Central）时，会自动生成 .module 文件，但需显式启用且满足前提：
- 使用
maven-publish插件（而非旧版uploadArchives） - 发布格式包含
components.java（Java 插件自动提供） - Gradle 版本 ≥ 6.0（推荐 ≥ 7.4，对 metadata 支持更健壮）
- 在
publishing块中明确启用：publications { myLib(MavenPublication) { from components.java } }
无需手动编写 .module 文件——Gradle 根据 dependencies 声明、configuration 类型（如 api/implementation）、variant 定义（如 JVM/JS/Android）自动推导并嵌入元数据。
确保依赖关系完整的关键配置项
元数据是否“完整可靠”，取决于你在构建脚本中如何声明和组织依赖。以下三点直接影响 .module 文件内容：
立即学习“Java免费学习笔记（深入）”；
-
用对配置类型：避免全用
compile（已废弃）。必须区分api（暴露给消费者）、implementation（仅内部使用）、runtimeOnly等。Gradle 将这些映射为 module 文件中的dependencyConstraints和variants，决定下游能否看到该依赖 -
显式声明可选依赖：若某依赖仅在特定场景生效（如日志桥接器），用
optional = true标记：api('org.slf4j:slf4j-api') { isOptional = true }—— 这会在.module中标记为optional=true，下游可选择不引入 -
锁定平台版本（BOM）：若你的库基于 Spring Boot，应在发布前用
enforcedPlatform统一管理传递依赖版本：dependencies { implementation enforcedPlatform('org.springframework.boot:spring-boot-dependencies:3.2.0') }—— 此约束会写入 module 元数据，保障消费者获得一致版本
验证元数据是否生效
发布后不能只看 .pom 文件——它不含 Gradle 特有语义。真正起作用的是同名的 .module 文件（如 mylib-1.2.0.module）：
- 访问仓库 URL 查看该文件是否存在（例如：
https://repo.example.com/mygroup/mylib/1.2.0/mylib-1.2.0.module） - 用
jq或文本编辑器打开，检查字段：
•"variants"是否列出jvm-runtime、sources等变体
•"dependencies"下每个条目是否含"group"、"module"、"versionConstraint"和"optional"字段
•"dependencyConstraints"是否包含你声明的 BOM 锁定规则 - 在下游项目执行
./gradlew dependencies --configuration runtimeClasspath，确认你的库所声明的api依赖确实出现在依赖树中，而implementation依赖不泄露
跨生态兼容性处理
若你的库需被 Maven 项目使用，元数据本身不影响 Maven 解析（它忽略 .module），但可通过以下方式兼顾：
- 在
pom.withXml中补充<dependencyManagement>块，把 BOM 信息同步进.pom - 对
compileOnly依赖（如 Lombok），确保同时声明annotationProcessor变体，并在components.java中注册对应 variant，否则 Maven 用户无法获得注解处理器支持 - 避免使用
capabilities或canBeResolved = false等高级特性，除非明确要求 Gradle-only 消费者
